diff --git a/_posts/2019-07-11-mdbook-toc-and-mermaid-preprocessors.md b/_posts/2019-07-11-mdbook-toc-and-mermaid-preprocessors.md new file mode 100644 index 0000000..a2c7756 --- /dev/null +++ b/_posts/2019-07-11-mdbook-toc-and-mermaid-preprocessors.md @@ -0,0 +1,163 @@ +--- +permalink: "/{{ year }}/{{ month }}/{{ day }}/mdbook-toc-and-mermaid-preprocessors" +title: "mdbook - ToC and Mermaid preprocessors" +published_date: "2019-07-11 13:40:00 +0200" +layout: post.liquid +data: + route: blog +--- + +[mdbook][] is a tool to create (online) books from markdown files. +It was created with Rust and is heavily used in the Rust community. Unsurprisingly the biggest and first user is [The Rust Programming Language Book](https://doc.rust-lang.org/book/). + +`mdbook` comes with most features you expect from it. It renders directly to HTML, +but also has alternative backends allowing it to [create ePub files][epub] or do some [link checks on the content][linkcheck]. + +However it lacks some more extensive features, which we required for some internal documentation. +So a while back I sat down and added this functionality. +Back then the only way to extend mdbook's rendering process with more elaborate features was by completely wrapping the mdbook code and add additional features. +`mdbook` was merely a dependency of whatever additional preprocessor was built. +This had multiple drawbacks: + +* Build multiple preprocessors into one tool or have one tool wrap other preprocessors +* You need to update the preprocessor's dependencies to get a new mdbook +* You need to use Rust to write the preprocessor + +As long as I controlled both the only usage and the code that was ok for our internal use, +but the `mdbook` maintainers realised that this is not viable in the long run for them, so they build a new way to use external tools as preprocessors. +This change should make it much easier to build and use multiple preprocessors. +I even got a PR to update one of my tools. + +I just never got around to merge and release that and then do the same for the other tool. +Until earlier this week a colleague asked me about the status of that tool, as he had similar requirements for their documentation. +So during work hours and yesterday's Rust Hack'n'Learn I sat down and integrated the missing pieces to release 2 mdbook preprocessors for easy reuse by others. + + +## mdbook-toc - add inline Table of Contents support + +`mdbook-toc` allows you to automatically create Table of Contents per chapter. +This becomes very useful when you got some long chapters with a lot of little subparts (and you don't want to split it up across chapters/pages). + +It turns this markdown: + +```markdown + + +# Header 1 + +## Header 1.1 +``` + +into this: + +```markdown +* [Header 1](#header-1) + * [Header 1.1](#header-11) + +# Header 1 + +## Header 1.1 +``` + +which eventually becomes: + +```html +