Pandoc — convert Markdown to HTML using a custom template

This is a tutorial on using Pandoc to convert Markdown to HTML using a CSS stylesheet and a HTML 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