The Intuitive Markup Language
Samples of Hugo’s extended CommonMark syntax to give a quick impression of the default layout.
Markdown has become the favored markup language to structure text files. With good cause: The Markdown syntax is very intuitive.
Headings introduce and order content segments on a page. Heading levels need to descend without interruption. We can modify headings only visually when we want to skip some levels.
Paragraphs are the essential building blocks of text. A comfortable line length and surrounding whitespace contribute to their legibility.
Sometimes we like to begin a new line without starting a whole new text block. Placing such a hard-line break gets complicated when hard-line wraps determine the line length inside the Markdown content files.
We have two types of emphasis to accentuate segments of our content: Light emphasis and strong emphasis. And we can nest both types.
To quote someone means to recognize her or his thoughts as part of our own. We may agree or disagree, but we should refer to them correctly.
A simple list is unordered and groups a set of related items. Any item may contain a sub-list.
Ordered lists group related items and mark them with ascending counters. They provide a very clear structure for a relatively short number of items.
The main text column offers space for 80 characters of code in one line. When we need more to fit in one line, we can let it expand into the marginal column(s).
Sometimes the separation of page segments by space is not clear enough. Then we can add this layout element as an explicit visual separation.
Internet references or short “links” are the binding fabric of the web. Markdown encourages their use by providing a few simple markup options.
There is only one Markdown image element but the theme distinguishes between two possible positions: stand-alone & embedded.
All available characters are valid Markdown. Here we talk about the ones that need special care: ASCII markup characters, HTML entities & exotic UTF-8 symbols.
Definition lists consist of terms as list markers, which are associated with details in the list entries.
Footnotes are best suited for (formal) information, which is not essential for the meaning of the text.
Markdown tables need some care, because their layout breaks, when the content of one row exceeds the available width.
Correction marks highlight changes while working on a draft. Lately, strike-through has also become a hip visual style.
A task list on a web page should be an interactive element which directly changes the corresponding Markdown. A theme can’t establish such a connection on its own.
Simple ASCII punctuation characters are substituted with typographic correct ones.
There is an extra markup in Hugo for vertically shifted characters in normal text.
Mark and highlight inline text as especially important.
GoAT renders ASCII diagrams as SVG and is a Golang implementation of Markdeep’s ASCII renderer.
We can preprocess images (rotate, change ratio, and zoom) and have several options for placing them in and around the text. We can add a caption. All this is achieved by additional parameters associated with the image source.
Layout options for enhanced images and their layout possibilities.
All the layout options for enhanced embedded images.
The theme relies on the powerful integrated Hugo methods.
Hugo’s attributes are plain HTML attributes getting injected from the Markdown source into the rendered HTML.
There is one box for framing content like a figure. And there are four kinds of annotation boxes for important messages: Danger, warning, info, and success.
When the content of a block fits nicely into a single column we can shrink & move it to the left or the right.
It’s easy to manually add anchors to any block element with an identifier attribute and to reference them with a Markdown link.
We can change the default layout behaviour of a Markdown block from a full-width layout block to an inline block, in case we want to place another element besides this block.
Sometimes we want the text to stop floating around an embedded element. We need a good ol’ .clear attribute, then.
.clear
All element-specific attributes are listed here to provide a kind of cheat sheet.
Text enclosed by curly braces { and } and special ASCII signs is replaced with missing Markdown tags after rendering.
{
}
Refer explicitly to keyboard strokes in your text.
This replacement code wraps the HTML tag around the marked content.
Sometimes we like to break a title or a line only for those layout versions, which show the text in full width.
Very long strings that are not hyphenated automatically may need an optional line break without a hyphen. We can generate the HTML tag with this replacement code.
Shortcodes can inject arbitrary and configurable HTML (or automated Markdown) in Markdown content — Hugo offers them as “Markdown’s hidden superpower”.
A marginal note contains additional important but nonessential information. It explains some context, sheds light on a detail or speculates on a given topic etc.
The first paragraph of every normal content page should contain a short introduction or summary. Usually, it’s also a good idea to mark this first paragraph with a styling attribute.
LaTeX is the most popular typesetting system for the natural sciences. The syntax has been established as a quasi-standard for complex mathematical formulas in print and web layouts.
Mermaid is a popular Javascript library creating SVG diagrams from text and code descriptions.
Generate SVG diagrams with the Kroki service by placing textual diagram descriptions into Markdown code blocks.
The project configuration file for the Markdown rendering engine in config/_default
This template file from the module hugo-mod-replacements contains the regular expressions for all replacement codes.
Punctuation Keymap of the German Keyboard Layout for Ubuntu.
Since version 0.126.0 Hugo offers to render additional inline markup for super- and subscripts, insertions, and marked content.
Demo for enhanced images and their layout possibilities.
Demo for the layout options of enhanced embedded images.
On large screens, code blocks expand into the margins as long as possible and may include up to 160 characters in one line.
Marginal notes add further information elegantly and unobtrusively. We can add them with the shortcode mnote.