Nefarius.Tools.XMLDoc2Markdown 1.8.0

XMLDoc2Markdown

Tool to generate markdown from C# XML documentation.

Based on the work of Charles de Vandière and Fernando Cerqueira ❤

How to use

Install tool

dotnet tool install -g Nefarius.Tools.XMLDoc2Markdown

Generate documentation

xmldoc2md <DLL_SOURCE_PATH> <OUTPUT_DIRECTORY>

Example

xmldoc2md MyLibrary.dll docs

Display command line help

xmldoc2md -h

Usage: xmldoc2md [options] <src> <out>

Arguments:
  src                          DLL source path
  out                          Output directory

Options:
  -v|--version                 Show version information.
  -?|-h|--help                 Show help information.
  --index-page-name            Name of the index page, (default: "index").
  --examples-path              Path to the code examples to insert in the
                               documentation.
  --github-pages               Remove '.md' extension from links for GitHub
                               Pages.
  --gitlab-wiki                Remove '.md' extension and './' prefix from links
                               for gitlab wikis.
  --back-button                Add a back button on each page with custom text,
                               (default: "< Back").
  --link-back-button           Set link for back button, (default: "./").
  --private-members            Write documentation for private members.
  --onlyinternal-members       Write documentation for only internal members.
  --excludeinternal            Exclude documentation for internal types.
  --templatefile               Layout template for documentation, (default:
                               "template.md").
  --back-index-button          Add a back button in index page, (default: "<
                               Back").
  --link-backindex-button      Set link for back button in index page, (default:
                               "./").
  --external-docs              Add an external documentation mapping in the
                               format <namespace>=<url-base> (repeatable).
  --external-docs-file         Path to a JSON file with namespace → URL-base
                               mappings for external documentation.
  --no-link-generic-arguments  Disable individual links for each generic type
                               argument (legacy rendering).
  --front-matter               YAML front matter (or @filepath) prepended to
                               every generated type page. Supports placeholders:
                               {TypeName}, {Namespace}, {AssemblyName}, {Date}.
  --index-front-matter         YAML front matter (or @filepath) prepended to the
                               generated index page. Supports placeholders:
                               {AssemblyName}, {Date}.
  --fail-on-unresolved         Exit with a non-zero code if any type reference
                               could not be resolved.

Tip — dependency resolution: if the tool fails with "Unable to load one or more of the requested types", the assembly's dependencies were not copied to the output directory. Running dotnet publish instead of dotnet build usually fixes this. As an alternative, add <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies> to the target project's .csproj to ensure all transitive DLLs are present alongside the documented assembly.

Template Tokens

{xmldoc2md-Title()}     = Title of Document
{xmldoc2md-Back()}      = back-button for pages 
{xmldoc2md-BackIndex()} = back-button for index page
{xmldoc2md-Body()}      = The Documentation

Example Template

# Custom Title :{xmldoc2md-Title()} 

{xmldoc2md-Back()}{xmldoc2md-BackIndex()}
- - -

{xmldoc2md-Body()}

- - -
{xmldoc2md-Back()}

Projects using XMLDoc2Markdown

The following open-source projects use this tool to generate their API documentation:

• Nefarius.Utilities.ETW
• Nefarius.Utilities.DeviceManagement
• Nefarius.Drivers.WinUSB