Markdown has become the favored markup language to structure text files. With good cause: The syntax is intuitive and there are a lot of possibilities to translate them into a visual layout format.

Markdown files consist of plain text marked up with a small set of ASCII signs. We can read and change them with any text editor. They usually end with the suffix .md.

After the original specification had been released by John Gruber in 2004, many slightly different flavors of Markdown emerged.

To resolve their incompatibilities and to create a general basic and dependable syntax, John Mc Farlane et al. proposed a strict specification in 2011: CommonMark. This specification has been implemented by many Markdown render engines since and important web-software providers thereby adhere to CommonMark as a kind of standard. For a quick look at the syntax you can visit their crisp one page overview.

Markdown for Perplex

Perplex styles HTML, which is generated from extended CommonMark by Hugo’s default renderer Goldmark. Three extensions — the definition list, the footnote and the typographer — have been adopted from PHP Markdown Extra. Based on CommonMark, GitHub introduced GitHub Flavored Markdown (GFM) with the four extensions table, the task-list, strikethrough and linkify. They are defined in a new specification.

Further extensions may join in the future, but probably only a few if any, because simplicity is essential for Markdown.

This documentation includes a short review of every syntax element in Goldmark and shows an example of its standard layout and alternative styling options with Perplex:

Basic Markdown Layout
covers the elements of the CommonMark specification.
Extended Markdown Layout
discusses the elements adopted from PHP Markdown Extra and GFM.

Caveats and Opportunities

Two basic Markdown elements are continuously creating confusion, because they are treated in somewhat ambiguous ways:

Image
The Markdown image element is syntactically meant to be placed inside a block element. But it’s also allowed to be used stand-alone and gets automatically enclosed by a paragraph then.1
Line Break
CommonMark and GFM are not fully compatible in regard to this one element. There are two different ways to handle line breaks inside of text blocks:
  1. Treat hard line wraps in Markdown files as whitespace like CommonMark does.
  2. Treat hard line wraps as hard line wraps like GFM.

The following suggestions for these elements are short. Their issues are discussed in more detail on their own pages.

How to include images?

There is one image element in Markdown for embedding an image into a block element and no genuine element for a stand-alone image, because the appropriate HTML tag <figure> is too complicated for simple markup. Hugo and Perplex provide the shortcode figure for this purpose.

A splashing drop of water
Stand-alone imageErda Estremera/ Unsplash

To surround every stand-alone Markdown image element with a paragraph — like CommonMark proposes and Hugo does — leads to a simple working solution, when the layout treats all images alike.

splash Embedded imageMulyadi/ Unsplash Perplex styles the Markdown image element as a float by default. Perplex also offers layout variations for both kinds of images. That’s why you should use the figure-shortcode for stand-alone images and the Markdown image element only for embedded ones, when you start fresh. Because of the widespread use of the Markdown image-element for stand-alone images, Perplex offers a fallback-parameter to show them in full text width.

How to wrap lines?

When we start writing Markdown, this question may not come to mind, because we often decide habitually: But should we still manually wrap the lines after a certain amount of characters — or better not?

Hard line wraps cause us and collaborating authors a lot of unnecessary trouble in the long run — that’s my impression. Almost all text editor programs are nowadays able to softly wrap long lines. Maybe we have to turn on that option for Markdown, but it should definitely be there.

When we rely on soft line wrapping everyone can read and edit the Markdown using a suitable line width. When we place manual wraps, everyone — including ourselves — has to deal with them again and again. They have to be moved or removed every time, when text is added or deleted.

How to handle hard line wraps remains your choice without any repercussions. Hugo can handle both ways perfectly, the decision only affects the editing experience.

How to break lines?

Our options here are tied to the way we wrap Markdown lines.

With Hard Wraps
When we us hard line wraps, to manually limit the line length, we can’t use them to indicate intentional line breaks inside of text blocks anymore. We need the special syntax CommonMark provides.
With Soft Wraps
If the lines are not wrapped, a line break is the intuitive way to place an intentional one.

See the page Line Break for the configuration and the question of CommonMark-compliance.

Special characters

All available characters — more general glyphs — can be used in Markdown, either directly as Unicode or as HTML entities (like &para; for ¶). The markup characters need to be escaped by a preceding backslash \ to get treated literally by the Markdown renderer. See Special Characters for more information about this topic.

File Encoding

The Markdown syntax works with every encoding. But almost all modern websites stick to the de facto standard UTF-8 and Perplex does, too. Your Markdown files should be encoded in UTF-8 and if you never thought about it before, they probably already are. This also holds for other text resources you may fetch data from.

Markdown Editors

Most programming editors and IDEs support Markdown out of the box or provide plugins. There’s no need to search for a new editor, if you are already satisfied with yours.

Some special editors are designed exclusively for authoring Markdown. They usually offer a graphical user interface and other convenient features. But none of them is a perfect match for writing Markdown for Hugo and Perplex, because they don’t support all kinds of attributes and can’t handle Hugo shortcodes — as far as I know (a few of them are progressing fast). They are dealing gracefully with these elements most of the time, but occasionally they don’t.

Many of these editors offer a convenient separate preview window. With Hugo you have an even better option: When you run Hugo in its web-server mode on the local machine you are writing your Markdown on, it will render your files and deliver the result to your browser instantly (see Using Hugo. My personal solution is either an IDE or a programming editor in conjunction with Hugo’s server mode.

Markdown Linter

CommonMark is permissive to small variations in the markup rules. To ensure a certain set of rules for a team or a bigger project, we may use a linter. The node package Markdownlint for example is reliable and there are plugins for editors, which allow to use it directly while editing.


  1. The corresponding <img/> tag is an HTML inline element and needs an enclosing block element in valid HTML 5. ↩︎