v2.61.0

[yufeih]

.NET 7.0 and C# 8, 9, 10, 11

This release adds support for .NET 7 and C# 8, 9, 10, 11. Docfx can now generate API docs for .NET 7 projects supporting all the latest C# language features including:

• Nullable reference types
• Default interface members
• Init-only setters
• Record types
• Record struct
• Checked user defined operators
• Static abstract interface members
• Required modifier

Display of API names and signatures have been updated to be more idiomatic C#, including but not limited to:

• Short familiar type names such as string, int
• ? for nullable structs and () for tuples

Markdown engine and custom markdown extensions

Markdig has been changed to be the default and recommended markdown engine in docfx. At the same time we are deprecating dfm and other markdown engines supported by docfx. Dfm markdown engine would be removed in some future releases.

To use a custom markdown extension in markdig, a ConfigureMarkdig build option is added to customize the markdig markdown pipeline:

var options = new BuildOptions
{
    // Enable custom markdown extensions here
    ConfigureMarkdig = pipeline => pipeline.UseCitations(),
}

await Docset.Build("docfx.json", options);

Client-side redirection

The new redirect_url metadata redirects a page to a new URL. To setup redirection for a markdown article, remove all markdown content and replace it with:

---
redirect_url: <URL to redirect to>
---

Known Issues

• Default nullable enum values displayed as numbers instead of enums Nullable enums in parameter value shown as numbers in SymbolDisplay roslyn#66514
• Nullable reference type in the parameters table missing ?.

What's Changed

💥 Breaking Changes

• BREAKING CHANGE: Set markdig as default and deprecate dfm. by @yufeih in BREAKING CHANGE: Set markdig as default and deprecate dfm. #8342
• BREAKING CHANGE: Drop modifiers from .NET API YAML output by @yufeih in chore!: drop modifiers from .NET API YAML output #8364
• BREAKING CHANGE: Drop builtin fsproj support by @yufeih in [BREAKING CHANGE]: drop builtin fsproj support #8375

🎉 New Features

• feat: Support building csproj targeting net7.0 by @yufeih in feat: Support building csproj targeting net7.0 #8349
• feat: Support redirect_url by @yufeih in feat: Support redirect_url #8340
• feat: Clickable console log by @yufeih in feat: clickable console log #8341
• feat: Allow custom markdown extensions by @yufeih in feat: allow custom markdown extensions #8358
• feat: Display C# API using SymbolDisplay by @yufeih in feat: generate C# API names using SymbolDisplay #8366 feat: display C# API declaration using SymbolDisplay #8367 feat: display C# referenced API name using SymbolDisplay  #8374
• feat: display C# special types using familiar format by @yufeih in feat: display C# special types using familiar format #8372

🐞 Bug Fixes

• fix: Set summary and conceptual to empty string instead of null by @NanoBob in Set summary and conceptual to empty string instead of null #8370

🔧 Engineering

• build: Upgrade to Jint 3.0.0-beta-2046 by @lahma in Upgrade to Jint 3.0.0-beta-2046 #8361
• build: Upgrade to YamlDotNet version 12.3.1 by @lahma in Upgrade to YamlDotNet version 12.3.1 #8373

📄 Documentation

• docs: Corrected typo by @Diagonir in Corrected typo #8368
• docs: Update docfx.exe_user_manual.md by @zp-zpanda in Update docfx.exe_user_manual.md #8377

New Contributors

• @lahma made their first contribution in Upgrade to Jint 3.0.0-beta-2046 #8361
• @Diagonir made their first contribution in Corrected typo #8368
• @NanoBob made their first contribution in Set summary and conceptual to empty string instead of null #8370
• @zp-zpanda made their first contribution in Update docfx.exe_user_manual.md #8377

Full Changelog: v2.60.0...v2.61.2

---

This discussion was created from the release v 2.61.0.

[KalleOlaviNiemitalo]

This discussion is titled "v2.60.0" but points to release v2.61.0 and to diff v2.60.0...v2.61.2.

[paulushub]

@yufeih Is on FIRE!!! Too bad my new contract is mainly Python and C/C++.

[mawosoft]

Markdown engine and custom markdown extensions

Markdig has been changed to be the default and recommended markdown engine in docfx. At the same time we are deprecating dfm and other markdown engines supported by docfx. Dfm markdown engine would be removed in some future releases.

The reason for using dfm has been the support for multiple YAML headers in a single markdown file. Does markdig provide that now?

[yufeih]

It seems markdig does not support it at the moment, are you using multiple YAML headers for overwrite files?

[mawosoft]

Yep. It's much easier to maintain them by type, rather than having a file for each member. I suppose a workaround would be to add a simple preprocessing step to split them up into temporary files and pass those to docfx...