The Intuitive Markup Language
Marginal notes allow to add further information in an elegant and unobtrusive way.
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.
Headings introduce and order the segments on a page. On a website with many pages, each level should have similar importance.
Paragraphs are the essential building blocks of text. Comfortable proportions and surrounding whitespace contribute to their legibility.
Sometimes we like to begin a new line without starting a whole new text block. To place such a hard line break gets complicated, when hard line wraps limit the line length inside our Markdown files.
We have two types of emphasis to accentuate segments of our content: Light emphasis or 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 but are tedious to read when they get too long. Consider to insert a normal paragraph or another block element in between the items of a long list.
The main text column offers space for 80 characters of code in one line. When we need 120 to fit in one line, we can choose to additionally use the marginal column.
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 bunch of simple markup options.
The CommonMark image syntax is short and simple and the theme generates a default layout for both kinds of images. To alter their appearance we need Hugo’s resource feature in the front-matter.
The theme allows to resize your stand-alone Markdown images and change their place in the layout.
Placeholder: Put your own introduction paragraph here instead of this one.
The theme relies on Hugo’s processing capabilities for image resources in page bundles.
All available characters are valid Markdown. The following sections are about the special ones we can’t use directly.
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 the typographic correct ones.
GoAT renders ASCII diagrams as SVG and is a Golang implementation of Markdeep’s ASCII renderer.
Hugo’s attributes are plain HTML attributes getting injected from the Markdown source into the rendered HTML.
It’s easy to manually add anchors to any block element with an identifier attribute and to reference them with a Markdown link.
Blocks with many short items can be more clearly arranged in columns.
All element specific attributes should be listed here.
We enclose a piece of text by curly braces { and } and add an ASCII sign after the first one. x{^3} for example gets turned into x3.
{
}
x{^3}
When you need only a few super- or subscripts in your Markdown, the replacement codes are there for you.
Refer explicitly to keyboard strokes in your text.
The <cite> tag has changed its purpose over time. It has been used to mark the name of authors, but today it should mark the name of creative works like books, articles or other websites.
<cite>
Hugo’s shortcodes can inject arbitrary and configurable HTML from within Markdown files. They are “Markdown’s hidden superpower”.
A marginal note contains additional nonessential information. It explains some context, sheds light on a detail or speculates on a given topic etc.
Because no Markdown element corresponds to the complex HTML <figure> tag, we need this shortcode for self-contained stand-alone images.
<figure>
LaTeX is the most popular typesetting system for the natural sciences, its syntax has been established as a quasi-standard to format complex mathematical formulas for print and web layout.
You can place your own lead paragraph here before the attribute .p-first and the more tag. If you don’t want to use special styling, just remove the attribute.
A definition list inside a blockquote with a sub-list in one of its items is an interesting problem for Markdown layout.
Markdown configuration file in config/_default
Punctuation Keymap of the German Keyboard Layout for Ubuntu.
The main text column offers space for 80 characters of code in one line. When we need 120 to fit in, we can expand code boxes into the marginal column(s).