Markdown tooling

Description or user story

• As a documentation author, I want a way to create internal links
• As a documentation author, I want to signify alerts with the same syntax as on markdown files on github.com.
• As a documentation author, I want the syntax for Janeway docs to match the github-flavored markdown spec. This is important for things like nested lists: GitHub lets you indicate a nested level with two or three spaces, while Pelican's default Markdown parser requires four spaces.

Potential solutions

• Use extensions with python-markdown (what Pandoc uses by default) so that we can add ids and classes like {#myId .my-class}
• Use pandoc to parse markdown via the Pelican pandoc-reader plugin and use Pandoc's gfm option
• Add a hook in the parsing in some other way to customise how some strings are transformed into HTML, to recreate the behavior of GitHub-style markdown alerts. This work has already been done in JS, but probably not Python.

This needs some investigation / experimentation to figure out the best solution.

Alternatives

• Give up the GitHub-style alert syntax, but add support for classes and ids