Encourage Markdown syntax in Gherkin?

[ciaranmcnulty]

The idea

On a recent contributors call it was discussed that some teams, and some tooling in the wild, already treats elements of Gherkin as Markdown.

I've definitely seen usages of:

• Bullet lists
• Emphasis with asterisks/underscores

What would be the benefits?

Being clear about Markdown flavour would aid interoperability

Recognising that Markdown is ok would encourage more elaborate usage, and encourage the tooling that doesn't currently treat it as markdown to start to do so - for instance Github could probably trivially improve how features are presented.

Some interesting ones that occur:

• More use of tables
• More use of hyperlinks
• More use of embedded images
• More use of embedded non-text formats (e.g. embed some GraphViz?)

What would supporting it look like?

We would potentially want to

1. Make it clear in docs which elements this applies to (e.g. in Feature/Rule/Example descriptions, but not in their names, probably not in scenario steps?)
2. Nominate a flavour of Markdown
3. Add gherkin testdata that contains complex markdown (e.g. do the 3-backticks collide with our docstring delimiters?)

What are the arguments against it?

There is already work being done by @aslakhellesoy to enable features-in-markdown, this may complicate or confuse the messaging.

The complexity of how tool authors and teams are using descriptions is their responsibility and we shouldn't peer into the formats being used.

There's a can of worms here

[ciaranmcnulty]

Another option is to have a syntax (like Markdown does TBH) that allows Gherkin to embed some other format inline. I don't know what delimiter make the most sense but it could be something like this, that would let users choose RST or something else if they prefer

Feature: This is my feature

    """markdown
   This is a _really_ important feature for our organisation...
    """

[mpkorstanje]

I imagine the parser might be quite confused by:

Feature: This might be a problem

Feature: This might be a problem

    Scenario: Example
        Given this example
```
Scenario: Example
    Given this example

[ciaranmcnulty]

@mpkorstanje Exactly the sort of thing I dunno

[aslakhellesoy]

I think we should encourage Markdown rather than “Markdown embedded in Gherkin”. The real thing rather than this weird thing.

The JavaScript implementation has a rough Markdown tokenizer. We could improve it and then port it to other languages.

[fullstackwebdev]

I use cucumber-js markdown daily with playwright. I recommend it thanks Aslak Hellesøy Markdown with gherkins

my feature files all end in .feature.md

there's some issues with non-cucumber tables rendering and you can't use ``` because it's being used as their docString.

[aslakhellesoy]

That’s great to hear @fullstackwebdev! Apart from you and me, I haven’t heard of anyone else using it. I don’t even think anyone on the core team is using it TBH.

That’s probably due to the lack of documentation and promotion. And as you’ve experienced, it’s a little rough around the edges.

Please do submit issues for any problems you encounter. I want to polish it and start promoting it and porting it to other platforms!

[fullstackwebdev]

thanks for your effort @aslakhellesoy

Here's my markdown workflow..

Surprisingly to me...I was able to persuade my clients, two non-technical co-founders, with a background in graphics design, spreadsheets, ... and I want to say, slightly above technical knowledge of computers (they used mac's back in the 90s) to learn markdown to write feature files. They are totally onboard and love it.

Given they can read and write markdown, they give me a markdown feature.md file (actually they take a Trello card first, then write it into scenarios) and put it into github. They put the figma screenshot at the top of the markdown feature file.

I take the markdown and obviously make changes (Add a background, convert some scenarios to outlines, etc) and go through each feature, scenario, and soon rules/examples.

I was able to convince them of this workflow because I described it as a "Contract" between "us and the solution." Not a legal contract, but a "if you describe this in specific detail, I can provide that". We call this an acceptance criteria but they do not have an agile background. The contract analogy made sense to them.

Vs, the "old way", which sucked:

I would receive wire-frames, mock-ups, figma drawings that looked absolutely wonderful with the general "idea" (not well thought out). But nobody had a clue what each button did. But when it came to building them, the turnaround sucked. The back and forth conversation and turn around increased. ("What does this button do? I don't know, let's have another meeting").

The contract driven development, leveraged by markdown, putting the wireframe at the top as a image, forces business users to fully think out their idea before it reaches me reducing round trip clarification meetings. Framing it as a contract causes them to be precautious and follow due diligent about their needs. Before, we had none of this. This is the value proposition. The markdown format also serves as a dual mandate that documents each and every step. The main repo's README is actually a link to a finished version of the feature.md markdown with a video at the top of playwright's recording of the test. On a side note, I have also hacked a subtitle of the feature name and steps into the video, but it's a work in progress. The video plays at an insane FPS but you can visually prove the solution works before pushing to production. This dramatically helps with communication. Reading and seeing it at the same time is another feature of markdown feature files, not possible with the old format (except of course finished reports)

The current non-markdown cucumber format doesn't allow for these things to happen, that's why I vouch for markdown as a feature file format. In the future, generally speaking, Markdown should be a skill alongside spreadsheets and word processors for business users.

I vouch for scrapping the old format entirely and switching to markdown. I'd love to be a part of this!

[ciaranmcnulty]

I think we should encourage Markdown rather than “Markdown embedded in Gherkin”. The real thing rather than this weird thing.

@aslakhellesoy in that case should we be discouraging the usage of markdown we see in the wild?

Or document a minimal subset (bold/italic/bullets) that we think gherkin formatters should be supporting?

[aslakhellesoy]

in that case should we be discouraging the usage of markdown we see in the wild?

It depends on what people are using to render feature files. Different tools have different Markdown support. For example, @cucumber/cucumber-react (and tools built on top of it) supports GFM. GitHub syntax highlights Gherkin, but not the Markdown inside.

Because of this I don't think we should encourage or discourage anything - it's just too rendering tool-specific to make a general recommendation.