carnarez / markdown-render

Opinionated way to render Markdown into HTML.

Templates for rendering Markdown into HTML. For my very opinionated usage.

Rendering

Server-side

Rendering done via Python-Markdown. Plenty extensions to deal with the fancy stuff, see below. Styling code (.css files) are processed through autoprefixer to add vendor prefxes.

Served files could be prettified via Prettier, but are currently minified using a mix of cssnano, html-minifier and terser.

Extensions

• AstdocsExtension to parse astdocs-specific syntax.
• DeleteSubExtension to introduce crossed out and subscript text.
• EmojiExtension to add support for GitHub emojis.
• FootnoteExtension to handle, well, footnotes.
• HighlightExtension to single out code blocks.
• ImgExtension for a [slightly] smarter image management via options embedded in the usual ![]() marker.
• InsertExtension to support addition of external content into the processed document via the &[]() marker.
• InsertSupExtension to introduce underlined and superscript text.
• MarkdownInHtmlExtension to parse and render Markdown located within HTML blocks.
• ScriptExtension to include JavaScript content via the %[]() marker.
• SuperFencesCodeExtension to enhance the processing of fenced blocks.
• TableExtension to render tables.
• TocExtension to generate the table of contents and anchor the titles.

Front matter

Front matter options (in valid YAML v1.1 format) are extracted from any index.md file via regular expression and properly parsed using PyYAML. Supported keys listed below.

The whole front matter block (including --- markers) is removed from the document before processing it.

Metatags

• author for the article:author metatag;
• description for the og:description metatag;
• image for the og:image metatag (above 1200x650 pixels for high resolution screens);
• date for the article:published_time metatag (YYYY/MM/DD format);
• tags for the article:tag metatag (list of keywords);
• title for the og:title metatag (defaults to the name of the folder otherwise);
• url for the og:url metatag;

Aside from title, all metatags are left empty if absent from the front matter.

Extras

• canonical to provide the canonical link of the article (defaults to url if not provided).
• link to provide a link to the author's favourite website.
• logo to provide a top-bar logo.

Client-side

Once generated, some extra rendering is done in the browser -i.e., on the client- via a couple JavaScript libraries:

• highlight.js for syntax highlighting.
• KaTeX to render equations written in LaTeX.
• Mermaid to render diagrams and flowcharts.

Deploy locally

Run make serve to get the HTTP server started at http://localhost:8000/ using a niftily patched thttpd as a very lightweight solution for local development and testing or the tiny solution shipped with BusyBox, httpd, although still slightly bigger than the thttpd solution previously used.