I started with the Mainroad theme, and gradually added customizations and extensions. (I spend way too much time fretting about formatting and not nearly enough time actually writing content - And the results are pretty mediocre in any case!)

Introduction

Many Flavours of Markdown

There are many variants of Markdown formats, and each processor may support a range of extensions, and interpret the Markdown specifications in somwhat different ways. The main formats include:

• Markdown - this is the classic orginal version
• Multimarkdown - the orginal extension to Markdown
• GitHub Flavored Markdown -a small set of extension to Markdown defined by GitHub
• Kramdown - extensive set of extensions based on PHP markdown Extra package and Maruku
• Pandoc - extensive set of extensions, but strays from the original markdown syntax and extensions somewhat

Markdown Processors

There are also many different Markdown processors, each with their own quirks. See the section [Other Markdown Processors and Formats] for details.

Introduction

This article focuses on markdown as supported by Hugo and Pandoc. Here are a few good Markdown references and tutorials:

• Markdown Guide
• Wikipedia Markdown entry
• CommonMark - the markdown “standard”

Hugo’s Markdown

Hugo uses the GoldMark as it’s default Markdown processor. Goldmark supports the CommonMark standard, along with:

• Tables, Strikethrough, Autolinks, TaskLists from GitHub-Flavored Markdown
• Definition Lists and Footnotes from PHP Markdown Extra
• Special typographic characters from SmartyPants
• Embedded HTML may be enabled in the Hugo Site Configuration
• Attribute lists on headings and block elements to add styling. See Hugo Site Configuration and Easier writing

Hugo Goldmark also supports:

• MathJax support, including AsciiMath, with the appropriate support in the theme layouts
• Syntax highlighting in fenced code blocks using Chroma syntax highlighter. See Hugo Syntax Highlighting for details.
• Emoji Support. Set enableEmoji to true in the main site configuration. For a list of emoji see Emoji Cheat Sheet

Pandoc’s Markdown

See Pandoc’s Markdown for details.

This page tests and documents using MathJax, Latex and AsciiMath with Hugo and markdown.

Getting a Markdown Processor to Ignore Markup

MathJax, AsciiMath, and similar processors use special markup characters in the the html file. Often these characters overlap with markdown’s markup, and the markdown processor will mess things up. There are a number of options:

• Use the \ backslash, which is markdown’s escape character, to escape characters that would be processed by markdown. See Escaping Characters in markdown

• Create a simple hugo shortcode which does nothing but pass through text verbatim, bypassing the markdown processor. Here’s an example of AsciiMath using the in (for inline) shortcode: