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!