Getting Started With DocFX

Published in

Hitachi Solutions Braintrust

6 min readDec 9, 2021

I recently needed to generate a documentation package for an API that had been developed for a client. During the process I reviewed several tools to help with the documentation generation process, and finally landed on DocFX.

Why did I choose DocFX? After learning that, behind the scenes, Microsoft used DocFX to create its documentation, it just made sense to use it as it would help make the documentation I needed look very similar to other types of documentation that developers are used to consuming.

What Is DocFX?

DocFX is a tool that produces a static website using both Markdown files as well as source code documentation. It is highly customizable in the way it allows you to modify templates and themes, and it can run in any environment! Since the output is a static website, it can be deployed to any number of hosts such as GitHub Pages or Azure.

Useful VS Code Extensions

The following list of extensions will help with development of your Markdown documentation that DocFX will use when generating the static site.

Where To Get DocFX

If you will be using DocFX strictly from the command line then the first option is to head over to the GitHub repo for DocFX where you can download both the latest stable V2 release as well as the V3 beta releases. A second option is to use Chocolatey: choco install docfx -y

The last option is to use NuGet to install the DocFX Console: nuget install docfx.console

If you wish to have DoxFX integrated with Visual Studio you may do that as well. Simply add a new class library to your solution and add the docfx.console NuGet package to your class library. When you build the library it will generate a folder for the static site contents. By default this will be _site.

For the remainder of this post, I will be using DocFX integrated with Visual Studio.

Default Folder Structure

After creating a new class library and adding the docfx.console NuGet package complete the process by building the new class library. Once the build completes you will find the following structure in your library:

_site

The _site folder contains the static site files that DocFX generated. The contents of this folder are what get deployed to your host platform.

api

The api folder will contain all the DocFX generated documentation files.

articles

The articles folder will contain your manually written Markdown files.

docfx.json

The docfx.json file is used to configure how DocFX generates documentation as well as what it generates documentation for.

index.md

The landing page for your static site.

toc.yml

The toc.yml file is used to populate the navigation header.

Configuring DocFX

The DocFX JSON file contains all the information DocFX needs to compile all the documentation sources into a static website. Modifying the following properties will allow for the flexible configuration of your DocFX project.

The metadata property lists source files, source directory, and the API destination directory.
In the properties collection, under metadata, you can define the TargetFramework for your project.
The build property lets DocFX know what type of files it should expect to build, where resource files are located, what files should be over written, and what, if anything, should be excluded from the site.
The exclude property, under build, can be used to limit what source code should not be included in the site.
The template property, under build, should always list ‘default’ as the first template, followed by any additional templates the site will be using. This allows you to inherit the default template and extend only what you need/want to. Any additional templates you wish to use should appear after the default template.

Launching The DocFX Site Locally

After building your DocFX project for the first time you can use a terminal to navigate to your DocFX json folder location and run docfx docfx.json --serve. This will build and serve your site locally and allow you to review how it looks as well as to review the site contents.

Making Changes To The DocFX Site

WARNING: If you are running your DocFX site locally, you will need to stop serving the site, rebuild the project, and then do a hard refresh to review changes made.

Add A New Section To The Top Navigation Bar

In your class library locate toc.yml. This is the main project table of contents. To add a new section, locate where in the order you wish to add the section.

Use the name parameter to give the section a name.
Use the href parameter to specify the navigation path.
Use the topicHref parameter to link to a specific file in the href folder.

Adding a New Subsection

Subsections can be added by linking additional toc.yml files to your project.

Templates

DocFX comes with some pre-defined templates for you to choose from. You can visit the DocFX Templates Page to review each one as well as locate the command needed in the DocFX json file.

For example, if you wanted to use the darkFX theme you would first need to download the theme. From there, create a new folder named templates at the root of your DocFX directory and copy the downloaded theme there. Then update the docfx.json under template by adding[“default”,”templates/darkfx”], and then rebuild your project.

Mermaid Template

Mermaid is a JavaScript-based tool that allows you to create diagrams and charts dynamically from Markdown. Mermaid supports several diagram types that are useful for API documentation such as flow charts, sequence diagrams, class diagrams, state diagrams, and many others.

For example, here is the Markdown for a simple sequence diagram, and then the rendered image that would be included in your static site:

While DocFX does not support using Mermaid out of the box, there is an option you can use to leverage this powerful tool. To use Mermaid in your DocFX project you will need to extend the default template. To do this simply add a new folder called mermaid in the template folder. Create a subfolder in mermaid titled partials and add new file titled scripts.tmpl.partial.

The contents of scripts.tmpl.partial looks like this:

<script type="text/javascript" src="{{_rel}}styles/docfx.vendor.js"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.0.1/highlight.min.js"></script><script src="https://unpkg.com/highlightjs-dotnetconfig@0.9.3/dist/dotnetconfig.min.js"></script><script type="text/javascript" src="{{_rel}}styles/docfx.js"></script><script type="text/javascript" src="{{_rel}}styles/main.js"></script><script type="text/javascript" src="https://unpkg.com/mermaid@8.10.2/dist/mermaid.min.js"integrity="sha384-nzpOk138h0/O14Ig1PAUlf1XSo5T+XvpBUVkpLaU40QBvMgrNkSKusdNAomDLEd2"crossorigin="anonymous"></script><script>mermaid.initialize({startOnLoad: false});mermaid.init(undefined, ".lang-mermaid");</script>

Conclusion

If you are currently using the Microsoft technology stack and you are looking to create meaningful documentation, then DocFX should be at the top of your list to review. It is highly customizable, both with themes and plug-ins, can be integrated in your CI/CD pipelines to automatically deploy updated documentation, and it produces documentation that will be very familiar looking to all the developers consuming it. As of the time of writing this article, my only drawback is the lack of support for generating swagger documentation from your OpenAPI 3.0 document. According to the GitHub repository though, the team is working on supporting it and it is expected to be released with version 3 of DocFX. However, there is no ETA on when V3 will be released.