Introduction

This article is a collection of all the default posts built into this Hugo theme. It covers everything about using Markdown for writing posts. I’ll only partially show how to write this directly in the .md file; the full version is available in this GitHub file. This article is mainly for me as an admin, so I can reference it to see how to write specific functionalities.

At the start of a post, you need to add a section called front matter. The documentation lists all the possible parameters you can include. You can set the front matter using either --- or +++. The difference is that --- follows YAML syntax, while +++ follows TOML syntax. In the settings, for example, you can add the field series = ["Themes Guide"]. This marks a series of posts on a particular topic, allowing readers to see related content. From what I understand, this appears in post recommendations at the end. However, recommendations should theoretically work even without it, based on shared categories and tags.

On the right, you’ll see a table of contents based on headers, which you can disable by adding toc: false at the top of the file. This table of contents only displays level 2-4 headers; deeper levels won’t be shown. You can modify this in hugo.yaml.

The post description shown on the main page is set at the top of the file in the description field. But you can enable a mode where a small portion from the beginning of the post serves as the description. For this, use the syntax <!--more--> at the point up to which the post description should appear.

Within Markdown, you can use HTML code to change the visual style. For example, I can make this text black on a pink background like this:

1

<span style="background: #FF5582A6; color:black">I can make this text black on a pink background</span>

If you want to include a Markdown symbol as plain text, without triggering any formatting, use \ before it. I did this with the example above, which originally looks like this: \<\!\-\-more\-\-\>.

When linking to another post, I prefer using absolute paths relative to the content folder. For example, if I want to link to a post in content/page/Archives, I’d write it like this, which in Markdown looks [like this]({{< ref “/page/Archives” >}}). This will work even if there are multiple .md files in the Archives folder for different languages. It will redirect to the page matching the user’s selected language.

A text divider, like the one below, is written as --- on a new line, with empty lines above and below it.

Simple Markdown

Headings

The following HTML <h1>—<h6> elements represent six levels of section headings. <h1> is the highest section level while <h6> is the lowest.

1
2
3
4
5
6

# H1
## H2
### H3
#### H4
##### H5
###### H6

Paragraph

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

Blockquotes

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Tables

Tables aren’t part of the core Markdown spec, but Hugo supports supports them out-of-the-box.

Inline Markdown within tables

Code Blocks

Code block with backticks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block indented with four spaces

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Code block with Hugo’s internal highlight shortcode

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

Diff code block

1
2
3
4
5

[dependencies.bevy]
git = "https://github.com/bevyengine/bevy"
rev = "11f52b8c72fc3a568e8bb4a4cd1f3eb025ac2e13"
- features = ["dynamic"]
+ features = ["jpeg", "dynamic"]

List Types

Ordered List

1. First item
2. Second item
3. Third item

Unordered List

• List item
• Another item
• And another item

Nested list

• Fruit
  • Apple
  • Orange
  • Banana
• Dairy
  • Milk
  • Cheese

Other Elements — abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL + ALT + Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

Hyperlinked image

Image gallery

You can create an image gallery where you can click on them and scroll through. For example, I have attached 4 images that ChatGPT generated upon request to create a logo for a Discord channel. In this example, there are three images at the top and one at the bottom, but when scrolling, they will cycle through seamlessly.

Emoji support

Emoji can be enabled in a Hugo project in a number of ways.

The emojify function can be called directly in templates or Inline Shortcodes.

To enable emoji globally, set enableEmoji to true in your site’s configuration and then you can type emoji shorthand codes directly in content files; e.g.

🙈 :see_no_evil: 🙉 :hear_no_evil: 🙊 :speak_no_evil:

The Emoji cheat sheet is a useful reference for emoji shorthand codes.

N.B. The above steps enable Unicode Standard emoji characters and sequences in Hugo, however the rendering of these glyphs depends on the browser and the platform. To style the emoji you can either use a third party emoji font or a font stack; e.g.

1
2
3

.emoji {
  font-family: Apple Color Emoji, Segoe UI Emoji, NotoColorEmoji, Segoe UI Symbol, Android Emoji, EmojiSymbols;
}

Math typesetting

Mathematical notation in a Hugo project can be enabled by using third party JavaScript libraries.

In this example we will be using KaTeX

• Create a partial under /layouts/partials/math.html
• Within this partial reference the Auto-render Extension or host these scripts locally.
• Include the partial in your templates like so:

1
2
3

{{ if or .Params.math .Site.Params.math }}
{{ partial "math.html" . }}
{{ end }}

• To enable KaTeX globally set the parameter math to true in a project’s configuration
• To enable KaTeX on a per page basis include the parameter math: true in content files

Note: Use the online reference of Supported TeX Functions

Examples

Inline math: $\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…$

Block math: $$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$

Hugo Shortcodes

Hugo ships with several Built-in Shortcodes for rich content, along with a Privacy Config and a set of Simple Shortcodes that enable static and no-JS versions of various social media embeds.

YouTube Privacy Enhanced Shortcode

Twitter Simple Shortcode

“In addition to being more logical, asymmetry has the advantage that its complete appearance is far more optically effective than symmetry.”
— Jan Tschichold pic.twitter.com/gcv7SrhvJb

— Design Reviewed | Graphic Design History (@DesignReviewed) January 17, 2019

Vimeo Simple Shortcode

bilibilibi Shortcode

Gist Shortcode

Gitlab Snippets Shortcode

Quote Shortcode

Stack adds a quote shortcode. For example:

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― A famous person, The book they wrote

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Anonymous book

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Some book

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

― Somebody

Links under post

To use this feature, add links section to frontmatter.

This page’s frontmatter:

1
2
3
4
5
6
7
8

links:
  - title: GitHub
    description: GitHub is the world's largest software development platform.
    website: https://github.com
    image: https://github.githubassets.com/images/modules/logos_page/GitHub-Mark.png
  - title: Support the Project
    description: If you enjoy what I create, you can support the author through this link.
    website: /donate

image field accepts both local and external images.