Both

• content/about/blog-posts.md
• content/about/related-tools.md

are full of really ugly badly escaped html, and probably need converting to also ugly markdown tables.

We need some kind of decent search:

Two obvious options are:

• Algolia free doc search
• Lunr

I suggest we implement both as long as it isn't too time consuming, and contrast and compare.

See https://cucumber.io/docs/reference/state

I don't know how to set a before hook, I'd like to read that page.

Would it be helpful to add an FAQ page? I've noticed some questions have come up several times just on Slack alone.
Examples:

• cannot find jvm v2.0 => group id has changed
• message that steps are not defined even though they are, due to glue path not being configured correctly

TOC doesn't seem to work for polyglot pages (when headings are inside language block).
For example: https://sw-menu--cucumber.netlify.com/installation/

Current behaviour
There's a small scrollable window that shows (part of) an open collective page containing input fields.

Expected behaviour
An Open Collective logo with link to the Cucumber contributions page

htmlproofer verifies internal & external links.
sometimes this failes the deploy on Netlify due to external sites not being available or giving timeout.
Add this information to README/CONTRIBUTING.md

Some of the Ruby examples look weird, similar to the number problem earlier (see #43).
Especially when using #{ ... }
This should be fixed (either in css or javascript)

A list of missing (or incomplete) pages in the new menu structure:

• "Documentation" ▶︎ Write a brief intro?
• Guides/10 minute tutorial (JavaScript) ▶︎ Write new content ▶︎ see #103
• Guides/10 minute tutorial (Ruby) ▶︎ Write new content ▶︎ see #104

Tasks

• Guides/BDD tutorial (Java) ▶︎ DONE (PR #93)
• Guides/Testable Architecture "How to have fast and reliable tests" ▶︎ DONE (PR #86)
• Guides/Browser Automation (NB. Marked "Old") ▶︎ DONE (PR #83 )
• Documentation/Configuration ▶︎ TODO: Move content from other places ▶︎ DONE (PR #85)
• Documentation/Overview - "a gentle introduction to Cucumber" ▶︎ DONE (PR #81)
• BDD/Who does what ▶︎ DONE (PR #81)
• BDD/Example Mapping ▶︎ TODO: Short version of Matt’s Example Mapping article, link to blog: https://cucumber.io/blog/2015/12/08/example-mapping-introduction ▶︎ DONE (PR #81)

Add a 10-minute tutorial on how to get started with Ruby, similar to #101

Info to get started:
https://docs.cucumber.io/docs/10-minute-tutorial.html
https://blog.codecentric.de/en/2013/08/cucumber-setup-basics/

https://www.netlify.com/docs/redirects/

Add a 10-minute tutorial on how to get started with Cucumber-js, similar to #101

Info to get started:
http://www.thinkcode.se/blog/2018/02/07/getting-started-with-cucumber-for-javascript
https://docs.cucumber.io/docs/installation.html#javascript
https://docs.cucumber.io/docs/10-minute-tutorial.html (select node.js)
https://github.com/denford/TuteCumber
Possibly: https://github.com/cucumber/cucumber-js

When I opened a PR with documentation updates on the main Cucumber repo, I was instructed to rebase my changes on this repo's sw-reorg branch.

Well, I did. And that’s cool. Trouble is, I still have no idea what the sw- prefixed branches are for. I don’t even know what “sw” means. :)

Can someone explain what the different branches are for? And how they relate to master?

If it does multi-language support out of the box, that would save us having to build our own stuff.

Need to check things like:

• is there a user-friendly way to edit the docs for @RebekahLawrence to use
• does it do multi-language support the way stripe's API docs do?
• is there enough flexibility in the nav to have nested levels of docs?

Anything else I missed?

Can you own this and have a look into it @aslakhellesoy?

jvm.md is not showing the cucumber jvm version

Actual result:
For instance:

<dependency>
    <groupId>info.cukes</groupId>
    <artifactId>cucumber-scala</artifactId>
    <version>{{ site.versions.cucumber_jvm }}</version>
    <scope>test</scope>
</dependency>

Expected result:

<version>2.1.0</version>

Being able to configure this version somewhere so it shows consistently through the document

Possibly this might help: https://gohugo.io/variables/

Update:

• TODO: cucumber/common#234 Gitbook link and article on cucumber-rails by @olleolleolle

Inspired by #33, I had a look at open PR's in http://github.com/cucumber/cucumber
I've closed a few that were outdated, but there are several others we should look at.
(PR's are labelled 'type: docs'.)

Nice to have: find them automatically

(As discussed on Slack between @aslakhellesoy and myself:)

Summary

All docs updates should be in the new docs.cucumber.io repo

Goal

Prevent duplicated / out of sync documentation, and/or rework to update documentation from other sources into this repo.

Solution

Add info to all individual sets of documentation (at least as mentioned in the README of this repo), placing a "do not update" warning somewhere, with an link pointing to this project for documentation updates.
Information should be placed where contributors are most likely to see that warning, starting with:

• Contributing.md file (s) in various repos
• Commit guidelines

TODO:

Add text with a link to this repo to the following repos/documents:

Note: Do not update documentation in this repo. We are busy adding old documentation to a new repository docs.cucumber.io to replace the current documentation on cucumber.io.
Please make ALL contributions to the documentation here.

Text should be added to:

• Contributing to Documentation: https://github.com/cucumber/cucumber/blob/master/docs/contributing-to-documentation.md (DONE)
• About this documentation: https://github.com/cucumber/cucumber/blob/master/docs/about-this-documentation.md (Updated to point to docs.cucumber.io)

Point CONTRIBUTING.md's in various repos to "Contributing-to-documentation.md" in docs.cucumber.io:

• Cucumber Community Contributing Guide 1.0: https://github.com/cucumber/cucumber/blob/master/CONTRIBUTING.md (?) (DONE: Updated link)
• Commit guidelines (=Cucumber Community Contributing Guide 1.0)

Contributing.md file (s) in various repos:

• 2008 onwards: Cucumber wiki (primarily Ruby)
  => https://github.com/cucumber/cucumber/wiki/Contributing (?) (Done: linked to new docs Contributing page)
• 2008 onwards: Misc README files for different implementations:
  • https://github.com/cucumber/cucumber-ruby
  • https://github.com/cucumber/cucumber-jvm
  • https://github.com/cucumber/cucumber-js
• ~~2015 onwards: https://cucumber.io/docs
  • Based on our own website app (Jekyll-like)
  • source~~ (DONE: Already removed)
• 2016 onwards: https://docs.cucumber.io/
  • Based on GitBook
  • source
  • See SUMMARY.md for the outline (DONE: Was removed)

I followed the docs and ran into an issue similar to this -

https://stackoverflow.com/questions/25291480/cucumber-exception-java-lang-classnotfoundexception-cucumber-io-resourceloader

I needed to make 2 fixes add the cucumber-core to my dependencies and also increment the cucumber-junit version to cucumber-java's versions (2.0.X)

I would like to send a pull for this if the community thinks this is a valid concern for beginners.

@plaindocs did you add the realartists.com webhook? What is it for?

I'm just cleaning up tickets on http://github.com/cucumber/website and there are four pull requests sitting open on the docs that have been there for a long time:

cucumber/website#8
cucumber/website#4
cucumber/website#3
cucumber/website#1

I'm going to close all of them now, but I suggest someone checks them over to see if anything valuable can be salvaged.

From @aslakhellesoy on November 25, 2016 22:41

Summary

People frequently use Cucumber alongside other tools. For various reasons, many end up asking questions about other tools in the Cucumber forums.

By providing a list of these tools, people are more likely to ask in the right place, and contributors can spend time explaining the same things over and over again.

i got the idea from this page: http://gitolite.com/gitolite/emergencies#things-that-are-not-gitolite-problems

Expected Behavior

User has a question about Selenium
Finds this page
Asks question in most appropriate place

User has a question about Selenium
Asks in Cucumber forum
Contributor sends short email pointing to this page

Current Behavior

User has a question about Selenium
Asks in Cucumber forum (can't find info suggesting a different forum)
May get a reply, may not, because it takes effort to write

Possible Solution

Have a dedicated page to the unrelated thing, linking to this page.

Context & Motivation

Users get more efficient at troubleshooting. Contributors get fewer irrelevant questions.

Copied from original issue: cucumber/common#97

From @aslakhellesoy on March 21, 2017 23:47

It's a bit daunting for newcomers to find out where and how to make changes.

• Do I contribute in monorepo or subrepo?
• How do they get synced?
• What directory?
• How does CI work?
• What software do I need?
• How do I run a build on my machine?
• How can I find issues to help on?
• Where do I send pull requests?
• When do I get commit rights?
• Who's on the core team?
• How do I make a release?

There are some docs about this in the root folder (some of them are out of date). CONTRIBUTING.md is too long and boring.

Let's steal shamelessly from these great projects (with credits):

• http://hood.ie/contribute/
• https://github.com/exercism/exercism.io/blob/master/CONTRIBUTING.md

Some general guides for inspiration:

• https://opensource.guide/
• http://www.firsttimersonly.com/
• https://opensource.com/life/16/3/contributor-guidelines-template-and-tips
• https://guides.github.com/activities/contributing-to-open-source/
• http://contribution-guide-org.readthedocs.io/#
• http://www.writethedocs.org/guide/

Copied from original issue: cucumber/common#167

There's one example missing for javascript in anti-patterns.md.
Java and Ruby examples for same are provided.
Missing example is marked "TODO" in the file.

I'm going to work on making our left menu more manageable, reduce some sections and lists, reduce white space, etc.

Maybe look at an mini TOC for each page that isn't injected into the menu.

Suggestions welcome.

Ruby code snippets are not shown correctly:

1. They're not formatted as code blocks
2. Text of the code block is also shown when Java or Javascript is selected for polyglot page

https://app.netlify.com/sites/cucumber/deploys/5a3cc0c88198767e07da8ff5

data from @mlvandijk in #89 :

The following links are failing on HTMLProoofer:
9:23:02 AM: * External link http://watirmelon.com/2011/01/21/my-simple-cucumber-watir-page-object-pattern-framework failed: 404 No error

External link http://watirmelon.com/2011/01/23/reducing-step-explosion-by-decoupling-cucumber-steps-from-your-gui failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/05/18/specification-by-example-a-love-story failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/07/04/the-elements-of-cucumber-style failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/07/04/use-cucumber-feature-folders-for-functional-organization-tags-for-non-functional-classification failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/04/capturing-screenshots-in-watir-webdriver-cucumber failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/07/keeping-the-browser-open-when-youre-writing-a-cucumber-test failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/08/making-your-cucumber-step-definitions-more-readable-with-rspec-binary-matchers failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/10/capturing-page-performance-times-with-my-watirmeloncucumber-framework failed: 404 No error
9:23:02 AM: * External link http://watirmelon.com/2011/08/29/running-your-watir-webdriver-tests-in-the-cloud-for-free failed: 404 No error
I've checked one of them and am getting:"Oops! That page can’t be found."
So these links need to be updated/removed(?)

I noticed the /.coafile and discovered it's for a linting tool called Coala, which I'm unfamiliar with. We should:

• Document what it is and how to use it in CONTRIBUTING.md
• Make sure it runs as part of CI

Hugo already generates the id so we need to add the link

https://discourse.gohugo.io/t/adding-anchor-next-to-headers/1726/9
or
https://stackoverflow.com/questions/42213736/hugo-automatically-link-headers

https://abouolia.github.io/sticky-sidebar/ maybe?

As we're not using these we should remove them for clarity.

And possibly replace with with a comment pointing to themes/cucumber-hugo/layouts/partials/navbar.html

The README.md specifies that when working locally, you should get the source code by cloning this project. If you do so, it is not possible to create pull request (403 error).
To be able to create a pull request, fork this repo to your own account, make changes there and create a pull request. (I have added this info also to my pull request: a7522cf)

Including:

• Conversational style: your project / feature vs a project / feature
• Use lower case in sentences: e.g. step definition vs Step Definition
• Don't use a period at the end of a bullet / numbered list (like this ;) )

Most of the pages in the current version of the docs don't vary according to your programming language, and it's misleading to show the language switcher tabs on those pages.

It would be better if we can have them only appear when we do have a page that has cross-platform docs on it.

@aslakhellesoy how would we go about doing that? We could disable the tabs by default and put a flag in the YAML frontmatter on the pages that do have cross-platform docs, for example.

Add info on Cucumber expressions
Source: https://docs.cucumber.io/cucumber-expressions/
(Note: while this URL is the same as the name of this project, the code for this content is actually not in this project)

Currently only available for Ruby afaik, but @mpkorstanje is currently working on implementing this for Jvm

Files marked with TODOs

• wiki/autotest ▶︎ TODO: Keep it or delete it? Note: No active pages link here
• cucumber/environment variables ▶︎ TODO: Make more general (seems to be a mix of Ruby and JVM?) Note: the following pages link here: cucumber.yml (but is not currently active)
  implementations/ruby/debugging ▶︎ TODO: Review for length Note: environment-variables links here (but is not currently active)
• /wiki/cucumber-backgrounder/ ▶︎ TODO: Blog post intro or some such (FYI: I did some editing in this already, on branch backgrounder) Note: No active pages link here
• cucumber/step-arguments-transforms ▶︎ TODO: Ruby specific feature. generalize. Note: No active pages link here
• implementations/ruby/browsers-and-transactions ▶︎ contains several TODO's Note: No active pages link here
• implementations/ruby/console-colours ▶︎ TODO: Review. Note: No active pages link here-
• implementations/perl ▶︎ TODO: Review (Merged/deleted)

Tasks

• implementations/ruby/custom-formatters ▶︎ TODO: fix link ▶︎ Does not contain any broken links, removed the 'TODO'
• cucumber/step-organization▶︎ TODO: integrate with step definitions and/or anti-patterns => Suggestion: merge & rewrite to make Good practices? ▶︎ DONE (PR #77)
• cucumber/running features ▶︎ TODO: Generalize ▶︎ DONE (PR #75)
• cucumber/mocking and stubbing ▶︎ TODO: Generalize and update ▶︎ DONE (PR #71)
• cucumber/checking assertions ▶︎ TODO: generalize (atm it has Ruby only) ▶︎ In progress, see PR #69 (Could maybe use more info on Javascript)
• cucumber/tags ▶︎ TODO: Gherkin and Cucumber. This is mostly Cucumber ▶︎ DONE (PR #63)
• gherkin/feature-introduction ▶︎ TODO: Gherkin reference ▶︎ DONE (PR #59)
• about/get in touch ▶︎ Suggestion: Replace with info from current 'Support'-page (https://cucumber.io/support) and move info about issues to contributing? ▶︎ DONE (PR #58)
• cucumber/hooks ▶︎ TODO: Important. Generalize. ▶︎ DONE (PR #56)
• gherkin/background ▶︎ TODO: Review. Add to gherkin reference ▶︎ DONE (PR #56)
• about/related tools - TODO: Clean and delete. Move to json? ▶︎ DONE (PR #45)
• cucumber/browser automation/#Watir ▶︎ DONE (PR #39)
• cucumber/feature coupled step definition (antipattern) ▶︎ TODO: Generalize. Move to Step Definitions (atm ruby only, adding java) ▶︎ DONE (PR #39)
• cucumber/step-definitions ▶︎ Some Ruby specific content ("Where are Step Definitions?") ▶︎ DONE (PR #50)
• implementations/ruby/calling-steps-from-stepdefinitions ▶︎ DONE (PR #50)
• Suggestion: merge step-definitions-old.md and step-definitions.md ▶︎ DONE (PR #50)

Edit by Zearin : Formatting to help read the long list :)

We have info on Maven, should also add info on Gradle

Not just current links to blog posts, but also:

• links to Cucumber books(?)
• links to Cukenfest videos.
• links to podcasts (directly to an overview of podcasts, not just from the cucumber blogs)

For Java

• Maven
• JUnit
• Cucumber
• Feature files
• Step definitions
• The application

'info.cukes' should be 'io.cucumber'

How to run features in described in different places.
Details differ per implementation.
Several things might go wrong here, which leads to questions.

Should include:

• cucumber/cucumber-jvm#934
• the glue location is the path from the java test sources folder

https://cucumber.netlify.com/documentation/

Would it be possible to show build status on readme, similar to what we have in other projects?

Sometimes the build fails due to (randomly) failing external links.
It would be nice if we could configure HTML Proofer to (for instance) retry 2-3 times if a check on a particular links fails

#Brain dump of links in sw-reorg which either need turning into proper markdown links [text](/path/to/file) or have the [[text]] removing.

Running grep "\[\[" in the content dir should give you an updated list.

wiki/cucumber-backgrounder.md
364:As with `Feature`, `Scenario` is used only for identification when reporting failures and to document a piece of the work. The clauses (*steps*) that make up a Scenario each begin with one of: Given, When, Then, And and But (and sometimes **\***). These are all [[Gherkin]] keywords / Cucumber methods that take as their argument the string that follows. They are the steps that Cucumber will report as passing, failing or pending based on the results of the corresponding step matchers in the step_definitions.rb files. The five keywords (and **\***) are all equivalent to one another and completely interchangeable.
489:Always keep in mind that Cucumber is simply a DSL wrapper around the Ruby language whose full expressiveness remains available to you in the step definition files (*but not in the feature files*). On the other hand, do not lose sight that every step called as such in a step definition file is first parsed by [[Gherkin]] and therefore must conform to the same syntax as used in feature files.

wiki/autotest-integration.md
57:If you get an error like `When using several—format options only one of them can be without a file (RuntimeError)` when running features with autospec, you are probably accidentally requiring 'spec'. Read about the solution on [[Troubleshooting]].

implementations/jvm.md
14:Please see the [[general reference]] for features that are
73:- [[Android Runner]]
149:The [JUnit Runner](#junit-runner) and [[Android Runner]] can also pick
187:Usage: java cucumber.api.cli.Main [options] [[[FILE|DIR][:LINE[:LINE]*] ]+ | @FILE ]
320:If you prefer to use a [[Data Table]] to define a list you can do that too:

implementations/ruby/ruby-on-rails.md
83:If you're on an OS that supports fork we recommend you use [[Spork and --drb]] as this lets you start cucumber faster:
163:Remember that you need AUTOFEATURE=true for autospec to include cucumber features. See [[Running Features]] and \[\[Autotest Integration]] for more info.
176:There are two special [[tags]] you can use to change how Cucumber runs your scenarios
180:By default all scenarios will run within a database transaction that is rolled back at the end. However, scenarios tagged with `@no-txn` will run **without** a transaction. This can be useful when you have to deal with [[Browsers and Transactions]]. Beware that this will leave data in your database after that scenario, which can lead to hard-to-debug failures in subsequent scenarios. If you use this, we recommend you create a Before block that will explicitly put your database in a known state, for example using [DatabaseCleaner](https://github.com/bmabey/database_cleaner)

implementations/ruby/calling-steps-from-step-definitions.md
63:Sometimes you want to call a step that has been designed to take [[Multiline Step Arguments]], for example:

implementations/php.md
95:The per feature and per table approach can be accomplished using [[hooks]].

about/blog-posts.md
10:Please add any helpful blog posts that you have found or written about all things Cucumber. Also see [[Related Tools]].

about/get-in-touch.md
41:- And finally, tell us how to reproduce the error, as described on the [[Contributing]] page.

about/contributing.md
12:Before you [[get in touch]] and file a ticket in the issue tracker, make sure you have tried the latest gem. Also try to \[\[install]] the latest code from Git. This way you don't waste the developers' time by reporting a bug that has already been fixed.
18:The only way we can fix a bug is to reproduce it first. If reproducing the bug requires setting up a project, please write a [[Cucumber Feature]] that demonstrates the bug. When you have done that, mention it in your ticket or send a pull request.
24:Start by creating a ticket. Then, create a [[Cucumber Feature]] and start implementing it. It also helps if you add RSpec specs for the low level code.

gherkin/gherkin-reference.md
10:the [[documentation overview]] for links to platform-specific documentation.
194:You can also use placeholders in [[Multiline Step Arguments]].

gherkin/feature-introduction.md
14:(or localized equivalent; Gherkin is localized for [[dozens of languages|Spoken

cucumber/step-definitions.md
44:Also check out [[Multiline Step Arguments]] for more info on how to pass entire tables or bigger strings to your step definitions.

cucumber/cucumber.yml.md
20:Defining a template requires a name and then the command-line options that you want to execute with this profile. The example above generates two profiles: the first, named `html_report`, with a list of command-line options that specify new output formats and a second, named `bvt` which executes all features and scenarios [[tagged|Tags]] with @bvt.
80:[[Environment Variables]] can be used in the profile argument list for a profile as you would normally specify one on the command-line.
95:[[Integration with Autotest|Autotest-Integration]] uses two profiles `autotest` and `autotest-all`. These profiles should be reserved for that service.

cucumber/running-features.md
70:Maven and Ant are described in [[JRuby and Java]]. MSBuild and Nant should be under [[IronRuby and .NET]]. Anything else - please contribute to this wiki!

cucumber/state.md
22:[[Before Hook]] to remove all data *before* a scenario starts.
24:This is usually better than using an [[After Hook]] as it allows
36:You simply tell Cucumber to start a transaction in a [[Before Hook]] and roll it back
37:in an [[After Hook]].
40:[[Tagged Hooks]] using a tag named `@txn`.
42:To enable it you have to tag every [[Feature]] or [[Scenario]]
58:The [[cucumber-spring]] module contains `@txn` hooks in the `cucumber.api.spring` package.
60:This package isn't on your [[glue path]] by default, so you have to add it yourself in your
61:[[Configuration Options]].

cucumber/step-organization.md
11:How do you name step definition files? What to put in each step definition? What **not** to put in step definitions? Here are some guidelines that will lead to better scenarios. If you are new to steps and the general syntax, please read [[Feature Introduction]] first.

cucumber/common#282

Might be related to this.

gohugoio/hugo#1778

We use # on in page headers, which render as H1. (which should probably be rendered as H2 anyway), and the in-page toc seems to think # and ## are of equal importance.