Export mdoc XML to HTML with mdoc-export-html

Run mdoc-export-html to turn an existing mdoc XML documentation tree into a browsable HTML site. Then check whether the export really ran, rather than trusting a silent exit: this guide uses the mdoc-export-html shipped by monodoc-base 6.8.0.105+dfsg-3.6ubuntu2 on Ubuntu. Allow about fifteen minutes if your XML tree and destination are already identified.

1. Check the installed command

Confirm which executable will run and inspect the local option spelling:

$ command -v mdoc-export-html
/usr/bin/mdoc-export-html
$ mdoc-export-html --help
usage: mdoc export-html [OPTIONS]+ DIRECTORIES

The help command should return status 0 and list --default-template, --ext, --force-update, --out, --template, --with-profile, and --with-version. Record the package version too: mdoc tooling has changed between Mono releases, and it is worth keeping in build notes when an export is part of a repeatable release.

2. Export into a separate destination

Choose an empty or disposable destination first. The -o option tells the exporter where to write generated files:

$ mkdir -p /path/to/html-output
$ mdoc-export-html -o /path/to/html-output /path/to/mdoc-xml

There is normally no progress report to interpret. The command reads mdoc-formatted XML below the directory argument and writes HTML into the output location. Keeping source and destination separate stops a later export accidentally becoming an input to the same job.

Checkpoint: inspect the destination without changing it:

$ find /path/to/html-output -type f -name '*.html' -print | head
/path/to/html-output/Some.Namespace/Some.Type.html

The exact names and subdirectories depend on the documentation identifiers in your source tree. If the list is empty, check that the directory really contains mdoc XML and that the command completed with status 0; an empty directory is not evidence that an HTML site was generated.

3. Understand the update rule

By default, the exporter writes a new output file only when the source documentation file is newer than the existing target. That makes repeated exports quick, but it can leave an old HTML file in place after you change a template or another input the timestamp check does not represent.

For a deliberate rebuild, add --force-update:

$ mdoc-export-html --force-update \
    -o /path/to/html-output \
    /path/to/mdoc-xml

Warning: this replaces generated files in the destination and has no undo option. Do not point it at a directory containing hand-edited pages unless you have a backup or can regenerate those edits. To recover from an unwanted rebuild, restore the destination from version control or a backup, then rerun the export with the intended inputs.

For a cautious first run, export to a new directory and compare it with the old site:

$ diff -ruN /path/to/old-html /path/to/html-output | less

A non-zero status from diff normally means differences were found, not that either directory is damaged. The comparison is read-only.

4. Save and use a custom XSLT template

The installed default template can be written to standard output, giving you a starting point:

$ mdoc-export-html --default-template > /path/to/mdoc-template.xsl
$ test -s /path/to/mdoc-template.xsl && echo 'template written'
template written

Review the file before using it. The template receives a Page XML document with fields including CollectionTitle, PageTitle, Summary, Signature, Remarks, Members, and Copyright. The generated HTML uses named classes such as PageTitle, Summary, Members, and MemberName; your stylesheet decides how those values are rendered.

Run an export with the reviewed stylesheet like this:

$ mdoc-export-html \
    --template=/path/to/mdoc-template.xsl \
    --force-update \
    -o /path/to/html-output \
    /path/to/mdoc-xml

Tip: keep the template outside the generated output tree, so a broad input search or a later cleanup step cannot mistake your source template for an exported page.

5. Choose the output extension

Generated files use the html extension by default. If your web server or publishing process expects another suffix, set it explicitly:

$ mdoc-export-html --ext=htm \
    -o /path/to/html-output \
    /path/to/mdoc-xml
$ find /path/to/html-output -type f -name '*.htm' -print | head

The extension changes the file names, not the source format. Keep it aligned with the links and server configuration that consume the generated files; do not assume an extension change also changes a web server's MIME configuration.

6. Restrict versions or profiles when necessary

Without filters, the installed command processes types and members regardless of version. Use --with-version for a specific assembly version, repeated when more than one version is wanted:

$ mdoc-export-html --with-version=2.0.5.0 \
    -o /path/to/html-output \
    /path/to/mdoc-xml

Or select a documented .NET profile such as net_4_0, net_3_5, silverlight, or monotouch:

$ mdoc-export-html --with-profile=net_4_0 \
    -o /path/to/html-output \
    /path/to/mdoc-xml

These options filter what is rendered; they do not convert an assembly to another target framework. If a page or member disappears, check the selected profile or exact assembly version before troubleshooting the XML.

7. Verify links and generated member anchors

Member pages generated by the tool carry an id attribute whose value is the member's String ID, which lets links target a particular member. Check a generated page as text:

$ rg -n 'id="|<title>|PageTitle|MemberName' \
    /path/to/html-output | head -n 20

Use the actual String ID from the generated page when building a fragment link. If a page has no expected member, revisit the selected profile or version. Also validate the finished site with the HTML checker used by your publishing system; mdoc-export-html reports export completion, not whether every link resolves in your web server.

Common traps

Done means