Live preview of Markdown documentation

Sun, 06 Mar 2016 18:16:06 -0000
pdo, staticsite, sw, eng

At work, to simplify build dependencies of DB-All.e we decided to port the documentation from LaTeX to Markdown.

Shortly after starting with the porting I resented not having a live preview of my work. I guess I got addicted to it with staticsite.

Actually, staticsite does preview interlinked Markdown files. I wonder if GitHub supports cross-linking between Markdown files in the same repo? It does, and incidentally it uses the same syntax as staticfile.

It shouldn't take long to build a different front-end on top of the staticsite engine just for this purpose. Indeed it didn't take long: here it is: mdpreview.

So, as you are editing the README.md of your project, you can now run mdpreview in the project directory, and you get live preview on your browser. If your README.md links to other documentation in your project, those links will work, too.

mdpreview uses the same themes as staticsite, so you can even tweak its appearance. And if you need to render the documentation and put it online somewhere, then staticsite can render it for you.

I experimented with it splitting staticsite's documentation into several parts, a I had great fun with it.

So, you want live preview of your project's Markdown documentation? mdpreview

When you are happy with it you can commit it to GitHub and it will show just fine.

You want it to show on your website instead? Build it with staticsite.

I'm considering merging staticsite and mdpreview somehow. Maybe mdpreview could just be a different command line front-end to staticsite's functionality. That's food for though for the next days.

Would you prefer to preview something else instead of Markdown? There is actually nothing markup specific in staticsite, so you can take this file as inspiration and implement support for the markup language of your choice in this whole toolchain. Except maybe for GitHub's website: that doesn't run on staticsite (yet).