So, the other day there was a hackathon at Geekskool and all the students were building something from the range of UNO bot, jump forms(feedback forms but better), and an app which detects code from an image and analyses/executes the same and there I was, wondering how to properly format nested lists in Markdown for one of my posts.
And thus started a long search of how to solve the issue of getting nested unordered lists in Nikola(which is a static site generator I use for this site.) So first things first, what does Nikola use to parse Markdown to HTML? Nikola docs say that it uses
Python-Markdown found on GitHub and I started checking for open issues, if any, about nested lists and I found one where the maintainer suggests to use 4 spaces for nested lists to work. And when I tried it, it looked bad with too much of space and hence I searched for alternative tools which supported GitHub-Flavored Markdown with the condition that I shouldn't have to make major changes to my existing setup.
That's when I came across Pandoc(though I had heard about it), I finally found a proper use case. Let's get started and solve the nested lists problem and whatever else that may come our way.
Install pandoc based on instructions from the official site.
Following are the modifications to be made to the
conf.py file of your Nikola site:
- Comment the
markdowncompiler and uncomment the
pandoccompiler in the
PANDOC_OPTIONSvariable and add
-f, gfmto the array;
-f/--frommeans the input format flag which is GitHub-Flavored Markdown hence the
And that's it, now when you build your site, Nikola will use pandoc and generate the site for you. However, there's a caveat. If you have any code blocks, the code highlighting theme doesn't seem to work now because the way pandoc generates is different than how Nikola expects it. A bit of info:
- Markdown file runs through the
markdowncompiler which gives
bodypart of the HTML and then Nikola inserts the rest of the
headand templated content and applies the style using Pygments.
- Whereas, Pandoc generates a complete HTML file with
styleinformation which Nikola unfortunately ignores and takes only whatever is inside the
bodytag and generates the final HTML with the templated content.
What we want is to preserve the style information so that code highlighting remains as how we want it. And so, started perusing the pandoc docs to be kind of disappointed that style information could not be generated as a standalone file as an input to Nikola. So, what I ended up doing is generate a dummy output file with some code as input to pandoc. Copy the following code snippet(or write some code of your choice) and paste it in a new file as
And run the following command:
$ pandoc -f gfm -o output.html input.md --highlight-style=kate -s
I personally like the
kate theme and for a list of supported themes check out the
--highlight-style flag in the Pandoc docs.
Now that you have a generated
output.html, open it and copy the generated
style information i.e. content inside the
<style> tags and paste them in the end at
After building your site, you should now see the syntax highlighted in the color theme that you selected while using pandoc. Currently, a minor hurdle is that whenever you want to change to a different theme, you should generate the style information and copy paste the CSS from the output HTML file.
So we have moved our Nikola site from
pandoc compiler with proper syntax highlighting.
- CSS for Kate theme used in this site: link