mdBook documentation generator

Tools
1

After looking at mdBook some more, I think this checks all my boxes:

  • works well with files in Git
  • direct translation of *.md → *.html
  • single file (SUMMARY.md) to generate the table of contents. This is much nicer than sprinkling meta-data in the actual markdown files which is difficult to update if you want to add a page to a site.
  • converts README.md → index.html
  • link checker

Currently working on converting the Simple IoT documentation to this format.

2

mdBook is part of the Rust project, but appears to be generally useful. There is work being done to make the playground feature work in other languages.

3

Improvements in mdbook v0.5.x

Other than generally looking nicer, the sidebar now dynamically shows page headings for the page you are on, eliminating the need for clunky TOC add-ons.

The SimpleIoT docs have been updated.

image
image785×848 63.6 KB

4

mdbook Docker container

I created a mdbook container that includes mdbook and some of the plugins I use.

https://github.com/simpleiot/docker-mdbook/pkgs/container/mdbook

While it is reasonably easy to install cargo and use that, it is slow and tedious to make sure everything is included. Also, we are increasingly needing containers for CI/CD workflows, so it often makes sense to use them for development as well.

This is now used to build the SimpleIoT documentation.