Pandoc — convert Markdown to HTML using a custom template

While converting Markdown to HTML using Pandoc, you can use an external CSS stylesheet using the -c option:

pandoc -s README.md -c custom.css -o README.html

The command assumes you have the custom CSS ready. If not, one possibility is to use a classless CSS stylesheet. I came accross MVP.css recently and liked how it looked.

Using MVP.css§

To use MVP.css for documenting a project I’m working on, I had to make some changes to Pandoc’s default HTML template. These are the steps I followed.

Getting the default HTML template§

First, I saved the default template to a file:

pandoc -D html > template.html

Modifying HTML template§

Then, I made these changes in template.html:

• Move TOC to a dropdown menu in site navigation
• Add a button with a link to the project website
• Update colour scheme using CSS variables and made some minor adjustments to styles

Using the modified template§

After adding some YAML metadata ¹ to README.md, I ran pandoc again with the modified template and CSS file to generate the final output:

pandoc -s README.md -c mvp.css \
--template template.html --toc \
--toc-depth=2 -o README.html

This is how README.html looks, before and after:

Download template§

You can download the modified template along with all required files from this repository on GitLab.

Useful links§

Pandoc home page
Pandoc usage examples
Pandoc documentation on templates
Sakura is an alternative stylesheet
More classless css stylesheets