Markdown

Markdown has become the favored markup language to structure text files. With good cause: The Markdown syntax is very intuitive.

Welcome to Markdown formatting!
-------------------------------

For a **quick introduction**, 
take a look at this one page
[intro](https://CommonMark.org/help).

Markdown files contain plain text marked up with a small set of ASCII signs. We can read and change these files with the suffix ›md‹ with any text editor.

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 minimal standard. For a quick introduction, you can visit their crisp one page overview.

Markdown for Hugo & this theme

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 their new specification (based on CommonMark).

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 for Goldmark and shows their standard layout and many enhanced styling options:

Basic Markdown

covers the elements of the CommonMark specification.

Extended Markdown

discusses the elements adopted from PHP Markdown Extra and GFM.

Enhancing Markdown

shows techniques to enrich the layout based on Markdown content.

Caveats and Opportunities

Two CommonMark elements are sometimes confusing because they are treated in 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 by pure CommonMark renderers.¹

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 only 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 situations and allows to generate the appropriate image containers:

Stand-alone image

Embedded image

Fig 2: Embedded float(Mulyadi/Unsplash) Perplex styles the embedded Markdown image element usually as a floating element inside its text block.

The theme offers many layout variations for both kinds of images: We can place embedded images on the left or right inside the text block and make them smaller than the default width you see here. Small stand-alone images may appear in the margin of the following text block. And large ones may be stretched completely from the left margin to the right.

You can find all options in the section for enhancing images.

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 at least. 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 our 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 may be used in Markdown files, either directly as Unicode or as HTML entities (like ¶ for ¶). Only Markdown’s ASCII markup characters need to be escaped by a preceding backslash \ to get treated literally by the Markdown renderer. (See Special Characters.)

File encoding

The Markdown syntax works with every encoding. But almost all modern websites stick to the de facto standard UTF-8 and this theme 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.

Using Hugo’s server mode for local previews

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

frontmatter CMS

frontmatter 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 frontmatter in a way that alters the site structure. It’s also not capable of handling Hugo’s resource parameters and local data files for resources. The plugin 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 we may use a linter. The node package Markdownlint for example is very reliable and easy to configure. There are plugins to automatically scan your Markdown directly in the editor.