[LucasGois1]

🔍 Problem statement

Closes #780.

gherkin-official already ships a Markdown with Gherkin (MDG) token matcher, but pytest-bdd cannot use it:

• every file is parsed with the default matcher;
• directories are searched only for *.feature files.

As a result, .feature.md files cannot be used.

🛠️ What's changed

• Files whose name ends in .md are parsed with GherkinInMarkdownTokenMatcher.
• scenarios() also collects *.feature.md files from directories. Other Markdown files, such as README.md, are not collected.

The rest of the pipeline does not change, because MDG produces the same Gherkin document as a .feature file.

Older gherkin-official releases. Before 32.2.0, the Python Markdown matcher crashes on any MDG document, including a minimal one:

AttributeError: 'bool' object has no attribute 'rstrip'

I reproduced this with 29.0.0, 32.0.1 and 32.1.0 through 32.1.2. Version 32.2.0 parses correctly.

I kept the existing >=29.0.0 dependency range. With an older release, a Markdown file raises FeatureError naming the minimum version instead of crashing. If you would rather raise the floor to 32.2.0 and drop the check, I can do that.

✅ Checklist

• I have added an entry to CHANGES.rst.

• The changes are covered by tests. The new tests/feature/test_markdown.py covers:

  • collection next to .feature files, with README.md ignored;
  • Background, inline-code tags turned into markers, doc strings, data tables and an Outline with an Examples table;
  • @scenario binding a scenario by name;
  • the line number of a syntax error;
  • the version error, which runs only on older gherkin releases.

  Results on Python 3.14:

  • The full suite, ruff and mypy pass with gherkin-official 42.0.1.
  • The new tests pass on 32.2.0.
  • On 29.0.0 and 32.1.2, the version-error test passes and the others are skipped.

• I have updated the documentation where necessary. The README gains a short "Markdown with Gherkin" section, including two MDG rules that surprise people:

  • a fenced block directly after a step becomes that step's doc string;
  • inline code such as `@slow` in a prose line is read as a tag line.