Nefarius.Tools.XMLDoc2Markdown 1.6.1

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: "./").

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()}