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.

• What it does not do: compile assemblies, create mdoc XML, publish a website, or add CSS to an existing site.
• You need: a shell, a readable directory of mdoc-formatted XML, and write access to the output directory.
• Placeholder: the examples use /path/to/mdoc-xml; replace it with a real documentation tree before running anything.

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.

$ 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

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

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

• Nothing changes: the destination may be newer than the XML. Use --force-update in a clean destination or after taking a backup.
• Wrong option copied from another release: run mdoc-export-html --help on the machine doing the build. This installation documents --default-template and accepts long options with an equals sign.
• Unexpected content: omit filters for a complete export, or record the exact --with-profile and --with-version values used by the build.
• Permission denied: write to a directory you own. Only use elevated privileges when the source or destination genuinely requires them; running the whole export as root can hide a deployment mistake.