Skip to content

Convert the last hand-written C# example to a MarkdownSnippets snippet - #4133

Merged
martincostello merged 1 commit into
domaindrivendev:masterfrom
RaphaelFakhri:docs/3413-snippet
Aug 27, 2026
Merged

martincostello merged 1 commit into
domaindrivendev:masterfrom
RaphaelFakhri:docs/3413-snippet

Conversation

@RaphaelFakhri

Copy link
Copy Markdown
Contributor

Fixes #3413.

The conversion turned out to be nearly finished already. I inventoried every fence in every Markdown file in the repo, split by language and by whether it sits inside a <!-- snippet: --> region:

File C# fences Outside a snippet
docs/configure-and-customize-swaggergen.md 43 0
docs/configure-and-customize-annotations.md 13 0
docs/configure-and-customize-swaggerui.md 13 0
README.md 9 0
docs/configure-and-customize-redoc.md 8 0
docs/configure-and-customize-swagger.md 7 0
docs/configure-and-customize-cli.md 1 0
docs/migrating-to-v10.md 2 1

So the complete list of unconverted C# examples is one item: the ISchemaFilter.Apply example in docs/migrating-to-v10.md. package-readme.md, CONTRIBUTING.md and SECURITY.md have no fences, and AGENTS.md only has shell ones. The remaining non-C# fences are terminal, yaml, json, xml and one diff showing a public API signature change, none of which are compilable code.

That one example now comes from a new MigrationSchemaFilter type in DocumentationSnippets, so it compiles against the library like every other example.

One detail worth knowing, since no other snippet in the repo does this: the fence lives inside a bullet of the Migration Overview list. MarkdownSnippets preserves the indentation of the <!-- snippet: --> marker line, so an indented marker emits the anchor, the fence and the <sup> footer all indented to match and the bullet still renders as a single list item. If you would rather not depend on that, the alternative is restructuring the bullet so the example sits at column zero after the list, which is what every other snippet does. I left the code content identical, apart from the block's pre-existing mixed indentation and a trailing space on the closing brace, which the extraction normalises.

dotnet mdsnippets runs clean and is idempotent, markdownlint-cli2 against the repo's .markdownlint.json reports 0 issues, and DocumentationSnippets builds on net8.0, net9.0 and net10.0 with 0 warnings and 0 errors.

Separately, on #4127: the C# fences I added there can become guarded snippets by putting the preprocessor directives outside the begin and end markers, so the rendered page shows clean code while net8.0 skips the .NET 9 example. The two examples both declare a type named Priority, so they need separate files with distinct namespaces to keep the rendered text identical. Happy to do that in a follow-up if you want it done there too.

docs/migrating-to-v10.md carried the only C# fence in the repo that was not
generated from compiled source. It becomes a snippet from a new
DocumentationSnippets type, so the example compiles with the library.
@codecov

codecov Bot commented Aug 25, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.21%. Comparing base (98c3501) to head (8570a6c).
⚠️ Report is 12 commits behind head on master.

Additional details and impacted files
@@           Coverage Diff           @@
##           master    #4133   +/-   ##
=======================================
  Coverage   95.21%   95.21%           
=======================================
  Files         111      111           
  Lines        4115     4118    +3     
  Branches      843      844    +1     
=======================================
+ Hits         3918     3921    +3     
  Misses        197      197           
Flag Coverage Δ
Linux 95.21% <ø> (+<0.01%) ⬆️
Windows 95.21% <ø> (+<0.01%) ⬆️
macOS 95.21% <ø> (+<0.01%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@martincostello
martincostello merged commit 649c3a3 into domaindrivendev:master Aug 27, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

📖 Use MarkdownSnippets to generate snippets in documentation

2 participants