Nefarius.Tools.XMLDoc2Markdown 1.7.0

XMLDoc2Markdown

Tool to generate markdown from C# XML documentation.

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

See sample generated documentation here.

How to use

Install tool

dotnet tool install -g Nefarius.Tools.XMLDoc2Markdown

Generate documentation

xmldoc2md <DLL_SOURCE_PATH> <OUTPUT_DIRECTORY>

Example

xmldoc2md Sample.dll docs

Insert code example

You can insert custom code example into the documentation.

Create one file for each examples. Give them the full name of corresponding type, property, method,...

Add the CLI option: --examples-path with the path to examples files.

Examples

MyClassLib.MyClass.md

## Example

Lorem ipsum...

```csharp
new MyClass();
```

MyClassLib.MyClass.MyProperty.md

#### Example

Lorem ipsum...

```csharp
foo.MyProperty = "foo";
```

MyClassLib.MyClass.MyMethod(System.String).md

#### Example

Lorem ipsum...

```csharp
foo.MyMethod("foo");
```

MyClassLib.MyClass.#ctor.md

#### Example

Lorem ipsum...

```csharp
new MyClass();
```

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: <namespace>=<url-base>
                                (repeatable). Default mappings cover System.*, Microsoft.AspNetCore.*,
                                Microsoft.Extensions.*, etc. → learn.microsoft.com.
  --external-docs-file          Path to a JSON file { "Namespace": "https://..." } for bulk mappings.
  --no-link-generic-arguments   Disable individual hyperlinks for each generic type argument
                                (reverts to the legacy single-link rendering).
  --front-matter                YAML front matter prepended to every generated type page.
                                Use @filepath to read from a file.
                                Supports placeholders: {TypeName}, {Namespace}, {AssemblyName}, {Date}.
  --index-front-matter          YAML front matter prepended to the index page.
                                Use @filepath to read from a file.
                                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()}