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 1 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
-
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.