DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports
Events Video Library
Refcards
Trend Reports

Events

View Events Video Library

Zones

Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks

How does AI transform chaos engineering from an experiment into a critical capability? Learn how to effectively operationalize the chaos.

Data quality isn't just a technical issue: It impacts an organization's compliance, operational efficiency, and customer satisfaction.

Are you a front-end or full-stack developer frustrated by front-end distractions? Learn to move forward with tooling and clear boundaries.

Developer Experience: Demand to support engineering teams has risen, and there is a shift from traditional DevOps to workflow improvements.

Related

  • Why Documentation Matters More Than You Think
  • Why and How to Participate in Open-Source Projects in 2025
  • Bonsai Checklist: 5 Rules to Make Your Open-Source Project Popular
  • Solving a Common Dev Grievance: Architecture Documentation

Trending

  • DZone's Article Submission Guidelines
  • Beyond Java Streams: Exploring Alternative Functional Programming Approaches in Java
  • Understanding the Circuit Breaker: A Key Design Pattern for Resilient Systems
  • AI Agent Architectures: Patterns, Applications, and Implementation Guide

DocFX: The Next Documentation Tool to Consider?

In this post, we take a look at a new version of Markdown, DocFX Flavored Markdown, and how it can be used to create documentation for REST APIs.

By 
Chris Ward user avatar
Chris Ward
DZone Core CORE ·
Mar. 11, 18 · Review
Likes (3)
Comment
Save
Tweet
Share
14.1K Views

Join the DZone community and get the full member experience.

Join For Free

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.

Documentation code style

Opinions expressed by DZone contributors are their own.

Related

  • Why Documentation Matters More Than You Think
  • Why and How to Participate in Open-Source Projects in 2025
  • Bonsai Checklist: 5 Rules to Make Your Open-Source Project Popular
  • Solving a Common Dev Grievance: Architecture Documentation

Partner Resources

×

Comments

The likes didn't load as expected. Please refresh the page and try again.

ABOUT US

  • About DZone
  • Support and feedback
  • Community research
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Core Program
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 3343 Perimeter Hill Drive
  • Suite 100
  • Nashville, TN 37211
  • [email protected]

Let's be friends: