DocFX: The Next Documentation Tool to Consider?

I recently started some documentation work for a project written in C#, and after researching tooling for auto-generating docs from the code base and falling down a rabbit hole, I emerged from the other side and found DocFX. Microsoft owns the project, but I think they rescued it from an abandoned project at some point. While it has a lot of features well suited to C# code bases, I also unearthed a plethora of other fantastic documentation features to suit projects written in any language.

DocFX Flavored Markdown (DFM)

Bringing yet another flavor to the sometimes too simple Markdown, DFM includes all GitHub Flavored Markdown syntax and adds a lot of syntaxes specific to using DocFX to build your documentation. Some of the syntax is so useful and pleasant to use, I hope other platforms adopt it. This isn’t a comprehensive list, but here’s what I’ve found most helpful so far. You can find a full list on their website, but not all in one place.

UIDs

With DFM you can define unique identifiers for a file inside YAML front matter and then refer to that in article links, instead of a file or URL. This helps your links stay up-to-date, even if file names and paths change.

You can also use this UID in three different formats for links:

1. Markdown link: [link_text](xref:uid_of_the_topic)
2. Auto link: <xref:uid_of_the_topic>
3. Shorthand form: @"uid_of_the_topic"

File Transclusion

Including the contents from other files is a feature present in many other markup languages, but not in Markdown without extensions or plugins, and DFM brings it’s own option to the table.

You can include file contents inline with other content, or on a separate line with the following syntax:

[!include[<title>](<filepath>)]

However, read the disclaimers before using the syntax, as what you can and can’t include is a little confusing.

Code Transclusion

In a similar vein to including the contents of other files, including the content of code in external files is another standard feature of other markup languages. This is useful as you can maintain that code as a full project for testing and other purposes.

[!code-<language>[<name>](<codepath><queryoption><queryoptionvalue> "<title>")]

Read this for a full guide on the queryoption and queryoptionvalue values as this help with all sorts of useful uses, such as including certain lines from a code file.

I haven’t used this code inclusion feature in my project yet, but it’s comprehensive and much needed in Markdown, so make sure you have a good read of the docs.

Note Formatting

DFM supports smart syntax for marking an area of text as a ‘warning’, ‘tip’, or ‘info’ block.

> [!NOTE]
> This is a note.
> [!WARNING]
> This is a warning
> [!INFO]
> This is information

DFM transforms these into a div with the note type as a class, so DocFX templates should render these as you wish.

Tabbed Content

Again, another feature that adds to their documentation platforms through a combination of JavaScript and custom markup or HTML. However, DocFX again takes these ideas and has simple and concise syntax. You can create tabs of any content, for example, different code snippets or platform-specific information.

Tab group 1:

# .[Tab Text 1](tab/tabid-1)

Tab content-1-1.

# [Tab Text 2](#tab/tabid-2)

Tab content-2-1.

***

Tab group 2:

# [Tab Text A](#tab/tabid-a)

Tab content-a-1.

# [Tab Text B](#tab/tabid-b)

Tab content-b-1.

***

In case that wasn’t clear, the syntax follows this pattern:

• Each tab is a markdown title of any level.
  • The title content should be a markdown link.
  • The link target is #tab/{tabid} or #tab/{tabid}/{condition}. These need to be unique.
• Continue with any other content.
• End tab group with a markdown hr / ***.

Documentation System

Aside from creating its own Markdown flavor, DocFX also packs a pile of features that cover (most) of what you need for documenting a project.

Conceptual Docs

For any tutorials, guides, conceptual documents, etc. you use Markdown, and URLs reflect the file paths. DocFX has a ‘table of contents’ (TOC) concept that takes some time to understand, but it allows you to autogenerate menus, breadcrumbs, and ordering of items on them.

REST APIs

DocFX supports auto-generation of HTML pages from a Swagger file (in JSON format), and in combination with plugins, you can break up complex API specs into sections. The themes for APIs are simple, so don’t expect any of the mock-style servers that Swagger provides (yet).

Code Docs

If your code base is in C# then you’re in luck, you can also generate HTML documentation from annotations in your code base. It’s another slightly fiddly feature, as you can only create the intermediary YAML files from the code comments on Windows, but you can convert these files to HTML on any platform. Microsoft has put a lot of work into making their tooling cross-platform, but it is still lacking features here and there.

And There’s More

DocFX also includes a whole bunch of other small features seamlessly such as ‘edit this doc’ (only on GitHub for now), Visual Studio (and Visual Studio Code) packages, and the ability (again, slightly fiddly) to override REST API descriptions with content in Markdown files. The project is in its infancy, and (ironically) the documentation is lacking in places, you often come across cool features by chance, but that aside, the project shows a lot of promise, and I recommend you try it with your next documentation project.