~ 1 min read

Markdown to HTML5 with Beautiful CSS with Pandoc

Written by Brie Carranza

Here's how I did it.

The Problem

I maintain awesome lists and other “README only” repositories in Markdown. I would like to automagically generate nice looking HTML from that Markdown.

The Solution

The solution is a special pandoc incantation.

If you need to convert files from one markup format into another, pandoc is your swiss-army knife.

Say more…

I assembled a one-liner that reliably does the following:

  • Convert Markdown to HTML5
  • Apply custom CSS
  • Specify the <title> tag

To play along:

  • Write some Markdown and save it as README.md
  • Save some CSS in styling.css

If you do not already have a stylesheet that you like, I would recommend Pan Am, a simple CSS for Pandoc.

pandoc --css=styling.css -s -f markdown+smart --toc --metadata \ 
pagetitle="awesome ldap" --to=html5 README.md \
-o index.html

Automate the Generation

I use a GitLab CI/CD pipeline to automatically regenerate the HTML. The specific .gitlab-ci.yml that I use is available online. The generated HTML is served via GitLab Pages.

Read More

  • Tufte Pandoc CSS - This is another example of pretty CSS for use with Pandoc.
  • Pandoc’s Markdown - Information about how Pandoc understands Markdown.

See it in production.

This is the mechanism that is used to generate awesome-ldap.

What’s next?

Emoji!

Share: