TL;DR: Just here for the tool? Alright, find it here.

Using DocFx you can create “conceptual content”, that is content that is not API docs, but manually crafted content.

Such content often goes along with API documentation, providing content like how to guides, administration or installation topics, etc.

Sometimes it is desirable to have such content available as PDF documentation, rather than only as a web site. DocFx can generate a PDF form markdown files, as it can generate web sites. It does so by invoking wkhtmlpdf in the background.

As can be seen here, the basic idea is that you generate a toc.md file and list the chapters of your conceptual topics there.

For example a toc.md file may contain the following:

# Administration Guide
## Installation Procedure
### [Prerequisites](admin\prereq.md)
### [Installation](admin\install.md)
## Usage
### [Start & Stop](admin\start_stop.md)
### [Troubleshooting](admin\trouble.md)

Each referenced file (e.g. admin\start_stop.md) then contains the complete chapter, including sub chapters.

For example:

## Starting the Application
...
### Starting as a service
...
### Starting in the foreground
...

So far so good. Having a proper docfx.json file and running docfx.exe pdf you will get PDF file containing these topics, together with an introductionary TOC that reflects the toc.md file.

NOTE: You can customize many aspects of the PDF, much more that is obvious, by providing your own template. It is not that hard, see this for more information. This includes having page numbers, custom headers/footers per page, a cover page, etc. (This is probably a good topic for another post some time).

The one thing that is lacking is the ability to have numbered headings/chapters, that is have a structure like this:

X. Starting the Application
X.Y Starting as a service
X.Z Starting in the forground

It is possible to achieve somthing like this using a customized template and CSS counters like shown here for example. You can add your custom classes for H1, etc. into a custom template (see above).

This actually works somewhat, but misses one critical thing: the numbers don’t appear in the TOC. Additionally, I haven’t been able to get it working without resetting the header counts for each chapter listed in the TOC, making it somewhat useless.

Another option is to use the --xsl-style-sheet, however I haven’t been able get this working either. Somehow it was ignored.

I thus figured a pre processor like tool could help. It would parse a toc.md and the files it references, enumerating all the headings (markdown #, ##, etc.) and assign chapter numbers to them. The resulting output files would be written into an output directory that, after all is done, reflects the directory structure of the original files.

This could be done using regular expressions, some hand crafted code, or using a markdown parser. I opted for the last one, since there are a couple of mature libraries available for .NET and especially Markdig seems only natural, since that is what DocFx uses as well.

The actual code is rather straight forward and you can find it here. Yup, it is rather tossed together, but for the simple use case it solves it is sufficient.

The tool is also available on NuGet.

To complete the example from above, here is what the markdown files would look like after processing:

# Administration Guide
## 1 Installation Procedure
### [1.1 Prerequisites](admin\prereq.md)
### [1.2 Installation](admin\install.md)
## 2 Usage
### [2.1 Start & Stop](admin\start_stop.md)
### [2.2 Troubleshooting](admin\trouble.md)

and

# 1 Installation Procedure
## 1.1 Prerequisites

## 1.2 Starting the Application
...
### 1.2.1 Starting as a service
...
### 1.2.2 Starting in the foreground
...

Note that an artificial Level 1 heading is added to the content files of each level 1 from the TOC. In this case the first file for the level-1-toc-chapter is prereq.md so there the heading “1 Installation Procedures” will be added. The file install.md is also under the level-1-toc-chapter, but doesn’t need this header again.

The above approach works rather nicely for my purposes, YMMV of course.

BTW, instead of a standalone tool a DocFX plugin would have also been possible I guess. For now, I like the standalone approach better, because it is more easily testable and in general has no direct dependency to a particular DocFX version.