luckyluggi/docfxmarkdowngen

Docusaurus Markdown generator using DocFX.

DocFxMarkdownGen

Generates documentation for a .NET library in Markdown intended for Docusaurus using docfx.

Installation

dotnet tool install -g DocFxMarkdownGen
# now installed as "dfmg", use with "dotnet dfmg" or just "dfmg" if tools are in PATH

Usage

By default dfmg takes it's config from config.yaml, you can override the file using the DFMG_CONFIG environment variable.

outputPath: /home/jan/whatever/docs/api
yamlPath: /home/jan/gen/api

• outputPath is the path where the generated documentation will be placed, it is always wiped. Can be overriden with the DFMG_OUTPUT_PATH environment variable.
• yamlPath is the path where the .yml files generated by docfx metadata are placed, probably the api directory where your docfx.json file is. Can be overriden with the DFMG_YAML_PATH environment variable.
• indexSlug is the slug of the index page, defaults to /api.
• typesGrouping read below.
• rewriteInterlinks set this to true if encountering issues with links when building the site.

Types grouping

Example:

# ...
typesGrouping:
  enabled: true
  minCount: 1 # default is 12

If type grouping is enabled, types in namespaces with a number of types greater than or equal to minCount will be grouped by Class, Struct, Interface, Enum and Delegate in the sidebar.

Newlines

Example:

# ...
#brNewline: "  \n" # default is "\n\n"
#forceNewline: true # default is false
#forcedNewline: "  \n" # default is "  \n"

• brNewline is the string that will be used to replace <br/> tags in the generated markdown.
• forceNewline if true, will replace all newlines(\n) with forcedNewline.

Example sites

• RCaron
• (outdated) examples/discord-net-dfmg: example site done on Discord.Net
• (outdated) Log73

For creating your own site, head to:

• dfmg-template for a minimalish example
• dfmg-template2 for a more complete example with versioned docs and CI examples for deploying to GitHub Pages and Vercel from GitHub Actions

This project is not finished, if you find an issue or something missing in the markdown generated, please open an issue or even open a PR!