This post helps to explain
The orignal post by daringfireball outlined a way to write simply, in a way that is legibile, but with some context clues for how it could be rendered into html. Some have argued that that original specification was far from complete, and its ambiguity, especially with corner cases, has led to confusion and a disparate way of handling common situations.
Today, perhaps because of that early ambiguity, and because the original outline was quite limited, there are a number of different “flavors” of markdown, which complicates things. Some flavors are defined as a standard, and other standards are a de-facto standard derived from how a specific rendering engine works. Take pandoc, for example. The pandoc standard is defined by the pandoc manual – they are one and the same. Some common markdown flavors include
There are also implementations, including python-markdown, a library in python that forms the basis for a number of markdown-themed projects, as well as implementations in Go, Ruby, etc, that form the basis for other static site generators such as Hugo and Jekyll, respectively. Each implementation and its own idiosyncracies are layered on top of their chosen specification or loosely defined standard.
For me, the original markdown encompasses only the most basic use-case for markdown. When writing content oriented towards presentations, I tend to use pandoc’s presentation formatting, such as the div mark :::, it’s support of styling with braces ({style="background-color:000000;"}), and its support of a number of niche functions only available in pandoc.
When I’m writing for websites or documents, I want finer-grained control of styles, to be able to specify the size and placement of images, and to integrate with the pdf or html template it will merge with more tightly. Hugo, MkDocs, and Pandoc each support extra attributes, either natively or with the help of plugins, though the extent of their support is not 1:1.
And let’s not forget, code, math, footnotes, and potentially even inline citations and bibliographies. Coming from an academic background I spent many long hours in the past getting all these features working in one markdown renderer or another. For example, there are many ways to specify code blocks, but for me, I have already switched over to “fenced” code, such as:
```python
import os
def my_function(input):
pass
```
which renders as
import os
def my_function(input):
pass
This is enabled by including ``` before and after each code block, with the optional language specified right after the first fence (such as ```python). I like this method over the four-space indent because it enables code-specific highlighting to be integrated.
So… this means I need to reimplement markdown parsing in a way that matches my existing documents, so that I don’t need to reformat my documents to suit a new markdown flavor. For this, I followed how MkDocs does it: using the python-markdown library, with specific extensions for all my extra use-cases. Much of my markdown is written for an MkDocs endpoint, so this makes a lot of sense for me.
talk about {% static %}