Vimalkumar Velayudhan


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 -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 1 to, I ran pandoc again with the modified template and CSS file to generate the final output:

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

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

Pandoc HTML output comparison
View README.html

Download template§

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

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

  1. Otherwise these variables will need to be provided on the command line. 

If you have any questions or comments on this post, please send them by email to vimal (at) disroot (dot) org.

If you would like your comment to remain anonymous, please state that in your email. In any case, your email address will not be published.