Markdown

Markdown has become the favored markup language to structure text files. With good cause: Markdown syntax is relatively intuitive and can be rendered into several layout formats.

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 dependable basic 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 Markdown’s essential characteristic.

This documentation includes a short review of every syntax element of Goldmark and shows their standard layout and alternative styling options:

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 CommonMark elements are continuously creating confusion because they are treated in somewhat ambiguous ways:

Image

The CommonMark 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.¹

Line Break

CommonMark and GFM are not fully compatible regarding 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 as 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 pages.

How to include images?

There is one image element in CommonMark for embedding an image into a block element and no genuine element for a stand-alone image. Thankfully, since version 0.108.0 Hugo can distinguish both types and allows to generate the appropriate image containers:

Stand-alone image

Hugo and Perplex used to provide the shortcode figure for this purpose. It’s kept for backward compatibility in this theme. But the new solution is much more convenient and fits loads of already existing Markdown.

Embedded image

2. Embedded image(Mulyadi/ Unsplash) Perplex styles the embedded Markdown image element as a float. The theme offers layout variations for both kinds of images. We can place embedded images on the left or right inside the text block. Small stand-alone images may appear in the margin of the following text block. Large ones stretch from the left margin to the right. Look into the section about images for all the options.

How do we 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?

The 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 enable hard-line wraps, to manually limit the line length, we can’t use them to indicate intentional line breaks 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 can be used in Markdown, either directly as Unicode or as HTML entities (like ¶ 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.

Specialized editors

Some editors are designed exclusively for authoring Markdown. They usually offer a graphical user interface and other convenient features. As of now, none of them is a perfect match for authoring Markdown for this theme, 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.

Use Hugo’s server mode for local previews

Hugo offers a very convenient way of looking at your results instantly: When you run Hugo in its server mode on the local machine you’re writing your Markdown on, it will render your files and deliver the result to your browser (see Using Hugo. My workflow is like many others based on Visual Studio Code (VSCode) as a Markdown editor in conjunction with Hugo’s server mode.

Front-Matter CMS

Front-Matter CMS is an exciting plugin for VSCode which offers many nice features. Unfortunately, I can’t recommend it right now for this theme, because it may change the front-matter in a way that alters the site structure. It’s also not capable of handling Hugo’s resource parameters out of the box. The plugin probably handles other projects very fine and I hope to use it in the future.

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 to use it directly while editing.