Templates and Customization

The build stage of DocFX (see Basic Concepts and Pipeline) first produces a data model for every document. A template is a folder that turns each model into an output file. It contains three kinds of files:

Because templates are plain files, customizing a site usually means changing a few of them, not forking DocFX. The template property of the build section of docfx.json (see docfx.json) is an array of template folders that are layered: for every file the engine looks in the last entry first and falls back to the earlier ones.

The figure shows the lookup for three entries. A custom folder only needs the files it wants to change; everything else comes from the folders before it. This is why the official documentation recommends listing default before modern: the modern template relies on the default one for the preprocessors and for the files it does not replace.

DocFX embeds its templates in the tool. docfx template list printed five names in 2.81.0:

common and statictoc are building blocks for other templates and default(zh-cn) is the default template with Chinese resources. In practice you choose between default and modern.

Exporting both templates in the test project showed how much each one ships. The two exports together had 372 files, and most of the modern ones are code-split chunks of the Mermaid, KaTeX, MathJax and lunr language bundles; its own source files are few. This listing leaves out the bundled files:

The modern folder has no conceptual-page, REST API or TOC preprocessors of its own, which is why default must come first in the array. In the exported files public/main.css, styles/main.css and styles/main.js are empty, and public/main.js contains only an empty default export. They exist as placeholders for you to override.

The easiest customization needs no template folder at all: the templates read predefined metadata keys that start with an underscore. They are ordinary metadata, so they are set in globalMetadata, fileMetadata, a metadata JSON file (globalMetadataFiles) or the YAML header of a page, following the precedence described in docfx.json. The most useful keys, as documented for the two templates, are listed here; keys shown for one template are not read by the other.

The value of _appLogoPath and _appFaviconPath is a path in the output folder, so the image must be copied there by listing it in resource. The test project used this configuration, with a small SVG logo in images:

Source: DocFX docs: Template

The build succeeded with no warnings and the home page contained, among other things, the following elements:

The title is the page title ("Pocket Units", taken from the heading of index.md), a vertical bar and _appTitle. The search input is rendered disabled in the markup and is enabled by the script once it has loaded the index; the build wrote index.json next to the pages. No edit link was rendered, as expected with _disableContribution set. A build without _enableSearch did not write index.json.

The next step is a template folder of your own, appended to the template array. It can be anywhere in the project; the examples use my-template. For modern the two entry files are public/main.css and public/main.js.

Source: DocFX docs: Template

The page layout loads public/docfx.min.css first and public/main.css second, so your rules win without a higher specificity. The Bootstrap 5.3 custom properties (here the link colors) are the supported way to change the palette. After the build, the output file _site/public/main.css contained exactly the custom file, because the custom folder was the last entry.

Source: DocFX docs: Template

main.js is a JavaScript module whose default export is an options object; DocFX loads it when the page starts. The options come from the DocfxOptions type in the template sources (templates/modern/src/options.d.ts in the DocFX repository):

Source: DocFX repository: options.d.ts of the modern template

The default template has no options object. Its two files are plain: styles/main.css is loaded after styles/docfx.css, and styles/main.js is a classic script that runs on every page.

Source: DocFX docs: Template

With the template array set to default and my-default, the build copied the file unchanged to _site/styles/main.css.

Dark mode belongs to the modern template. Its page shell contains a small script that runs before the page paints and sets the data-bs-theme attribute of the html element, which Bootstrap 5.3 uses to switch its color variables:

Source: DocFX repository: modern template

The listing is taken from the exported modern page shell. A theme picker in the header lets the visitor choose light, dark or automatic, and the choice is stored in the browser under the key theme. The minified application script reads the stored value first and then the defaultTheme option of main.js, and falls back to auto, so defaultTheme: 'dark' only applies to visitors who have not picked a theme. To style a theme specifically, select on the attribute in public/main.css:

Source: DocFX docs: Template

The default template has no theme switch. A site that must offer a dark appearance with it has to supply its own CSS (for example with prefers-color-scheme media queries) in styles/main.css.

Any file of a template can be replaced by a file with the same relative path in a later template folder. Two cases cover most needs.

A preprocessor is a JavaScript file next to a template that changes the model before it is rendered. For a Markdown article the default template runs conceptual.html.primary.js, which calls two hooks defined in conceptual.extension.js: preTransform at the start and postTransform at the end. Overriding the extension file is therefore the lightest way to touch the model. This extension appends a suffix to every article title:

Source: DocFX docs: Template

With the template array set to default and my-ext, the home page of the test project got the title Pocket Units [preview]. Similar hooks exist for the API pages in ManagedReference.extension.js and RestApi.extension.js, and the shared helpers are in common.js of the default template.

A template author needs to know which variables a page receives. The docfx build command can write the data model that the preprocessor gets, using --exportRawModel, and the model after the preprocessor, using --exportViewModel. The related options choose the folders, and --dryRun skips applying templates so that only the models are produced:

Source: DocFX docs: Template

For the Pocket Units project this wrote one file per document, in a folder tree that mirrors the sources:

The model of the home page contained the content (conceptual), the title, every metadata key set by globalMetadata (_appTitle, _enableSearch, _enableNewTab, _disableContribution) and the predefined variables that the template page documents: _rel, _path, _navPath, _navRel, _navKey, _tocPath, _tocRel and _tocKey, plus a __global object with the localized UI strings. For the home page _rel was empty, for api/PocketUnits.Converter.html it was ../, which is why templates build links as {{_rel}}public/main.css. In 2.81.0 the --help text of docfx build describes the extension of the model files as .raw.model.json, while the files written by the run above were named *.raw.json; trust the files.

docfx template list shows the embedded templates and docfx template export copies one to disk so that you can read it or use it as the base for your own. The command takes a template name and an output folder; --all exports every embedded template:

Source: DocFX docs: CLI reference overview

The files appear in a subfolder named after the template (exported/modern/modern/layout/_master.tmpl), so the folder you add to the template array is exported/modern/modern. Export is the way to find out which files you can override, because the official Template page does not list them. It is also how to see which other settings a template reads: the Mustache fragments show every metadata key and __global string in use.

If you export a template to customize it, remove everything you do not change. A full copy listed after the built-in one still works, but it freezes the template at the DocFX version you exported: the Mermaid and math bundles in public, the search scripts and the layout are then no longer updated when you upgrade the tool. DocFX 2.81.0 also made search.min.js of the modern template overridable, for sites that need a different search front end, and the build writes the DocFX version that produced a site into manifest.json as docfx_version (the test build recorded 2.81.0 with its commit hash), which helps to find out which release an old site was built with.

The official documentation points to a Template Gallery for community templates and says the DocFX repository contains a seed sample with a custom main.js that registers an extra syntax highlighting language. Third-party templates are used the same way as your own folders: download or reference them and add the folder to the template array, after default and modern unless the template says otherwise. The gallery was not fetched for this page, so its current content is not described here. The old tutorials about writing a template from scratch, overwrite files and plugins are in an archive section of the DocFX documentation and are treated there as legacy, so the layering approach above is the recommended one.

For the comparison with the other documentation tools see DocFX.