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 Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
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

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.

Chris Ward user avatar by
Chris Ward
CORE ·
Mar. 11, 18 · Review
Like (3)
Save
Tweet
Share
12.98K 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.

Popular on DZone

  • Top 5 Java REST API Frameworks
  • Express Hibernate Queries as Type-Safe Java Streams
  • Event Driven 2.0
  • The Quest for REST

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

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

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: