Introducing DocNet, a static documentation site generator

Update:

Since release, I’ve updated the repository with a github site with Docnet’s own documentation: http://fransbouma.github.io/DocNet/ It can be used as a showcase how things look in the output and also is now the main documentation site for Docnet.

Also I’ve added Tabs support as a Markdown extension and fixes to the Theme!

Original post:

I wrote another generator! This time it’s for generating a static site for user documentation from markdown files. It’s called DocNet and it’s Open Source: https://github.com/FransBouma/DocNet. It took me a good 7 days to build it. We at Solutions Design use it to create our user documentation for the upcoming LLBLGen Pro v5.0 release. The documentation for the designer is currently being worked on and gives a good overview how the output of DocNet looks like: LLBLGen Pro v5.0 designer documentation generated by DocNet (Work in progress!)

The github repo contains a readme with all the options and how to use it, so I won’t mention it here again. It’s not complete yet, but it already can produce output we can live with. If you want to add features and work on this too, please feel free to provide a PR.

“Why?”

LLBLGen Pro exists now for 13 years. In those years the documentation has been shipped in .chm files and in recent years also as a static website generated from the same html files used to create the .chm file. If you’re not familiar with .chm files, they’re compacted archives, built with a compiler from Microsoft which hasn’t been updated in … 10 years? and use IE to render the pages (IE6’s render engine that is). In short, the format is completely outdated. Nowadays, documentation is shipped with HTML5 content, often online only, as a normal website. Additionally, the documentation is more and more written in Markdown. We wanted that too with our (massive) documentation for LLBLGen Pro. We had one extra requirement: the site should be equal locally as well as online, so people who have no internet connection at a given moment (airplane, train, dead wifi) can still browse the help locally.

So in short:

• Documentation has to be written in markdown
• Documentation site is browsable locally and online with the same content
• Existing documentation files have to be convertible to markdown
• Has to use standard HTML5 / CSS / JS output
• Has to look modern.

For our class library reference documentation I use Sandcastle Help File Builder, which is a brilliant piece of software. It works, output is known, no surprises, so that’s covered. The user documentation however, is another story.

There are many, many different tools on the market to produce user documentation for you, in a lot of different formats. There are two categories: 1) a big IDE which manages content / topics / structure and lets you edit the content per topic in some form of editor and 2) a tool which consumes a set of files and produces a bunch of html files which form your user documentation.

The tools in category 1) all do their job fairly well: some produce uglier output than the other, but in general they all are capable to produce user documentation that’s readable and usable. As we already have a massive amount of documentation in html files (which are hand-written in the vs.net html editor), the tools in this category didn’t really fit. This isn’t their fault, but simply our situation.

The tools in category 2) are most of the time either in python, javascript or … php! Yes I was surprised too. The quality of these tools is often ‘ok’ but also need some work on your part. The tool which actually produced decent output was MkDocs. MkDocs is the tool that I had chosen at first but its local site doesn’t work at all, and its ReadTheDocs theme (the one worth using) has ‘always expanded ToC entries’ which isn’t usable if you have many topics like we do.

So in the end, I thought: “what can I build in a couple of days?” After all, it’s markdown in, html out. With a decent Markdown parser, how hard can it be? Not that hard, it turned out. I called the result of my 7 day hackathon: DocNet.

Converting Html to Markdown

Though, you might wonder now however that there’s a missing piece in the puzzle: how did we get from html files to markdown files? That’s rather simple: Pandoc! Pandoc is an amazing toolkit which can convert text in a wide range of formats into whatever format you want. So I wrote a little batch file to traverse the .html files and convert them with Pandoc to markdown files. Then I opened all of them in Notepad++ which allows me to search / replace blocks of multi-lined text and cleaned up the header/footer div tags which were left by Pandoc in one go. Then I opened the old help compiler ToC file in notepad++, as it’s just crippled HTML, and used some search / replace to convert it into a tree I could use with DocNet’s config file.

That was basically it!

Per page there are of course things which need adjustment, but it’s relatively minor: we used tabs/collapsible sections which are now replaced with plain markdown, the Note sections are now replaced with a markdown extension we added in DocNet, but it’s all easily corrected.

I hope DocNet is as useful to you too as it is to us.

Happy documenting!