Typography and Markdown

This guide covers all the basic Markdown formatting options available in the theme.

Basic Text Formatting

As is standard in Markdown, the basic formatting options are:

• Bold text is created using double asterisks: **bold text**
• Italic text is created using single asterisks: *italic text*
• Inline code is created using backticks: `inline code`
• Strikethrough: created using double tildes: ~~strikethrough~~
• Links are created using: [Link Text](https://example.com)

Headings

Mono supports six levels of headings, each with appropriate sizing and spacing for clear visual hierarchy, which are created using hash symbols:

# Heading 1
# Heading 2
## Heading 3
## Heading 4
### Heading 5
### Heading 6

Blockquotes

Blockquotes add visual emphasis to quoted text or important notes. We can create them using the > symbol:

This is a blockquote with a single paragraph. Blockquotes are useful for highlighting important information or quoting sources.

We can also have nested blockquotes:

This is the outer blockquote.

This is a nested blockquote.

Back to the outer blockquote.

Inside the blockquotes we can write our Markdown elements as normal:

Here is a blockquote with various Markdown elements:

• List item in a blockquote
• Another list item

Bold text and italic text work in blockquotes too.

Lists

This is the standard way to create lists in Markdown.

Unordered Lists:

• Item 1
• Item 2
• Item 3

Markdown:

* Item 1
* Item 2
* Item 3

We can also use the - instead of *.

Ordered Lists:

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

Markdown:

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

Nested Lists: Lists can be nested by indenting items with spaces:

• Main item 1
  • Nested item 1.1
  • Nested item 1.2

Markdown:

* Main item 1
  * Nested item 1.1
  * Nested item 1.2

Task Lists: Task lists provide a way to create checkboxes for to-do items:

• Uncompleted task
• Completed task
  • Nested uncompleted task
  • Nested completed task

Markdown:

- [ ] Uncompleted task
- [x] Completed task
  - [ ] Nested uncompleted task
  - [x] Nested completed task

Definition Lists: Definition lists can be used for glossaries or term explanations:

HTML

Hypertext Markup Language, the standard markup language for creating web pages.

Used by browsers to structure and display content on the World Wide Web.

CSS

Cascading Style Sheets, a style sheet language for styling web pages.

Describes how HTML elements should be displayed.

Markdown:

HTML
: Hypertext Markup Language, the standard markup language for creating web pages.
: Used by browsers to structure and display content on the World Wide Web.

CSS
: Cascading Style Sheets, a style sheet language for styling web pages.
: Describes how HTML elements should be displayed.

Horizontal Rules

Horizontal rules (lines) can be created using three or more hyphens ---, asterisks ***, or underscores ___. This will appear as follows:

Footnotes

Footnotes allow us to add notes and references without cluttering the main content:

This is a paragraph with multiple footnotes¹. We can add explanatory notes² throughout the content. Footnotes can contain formatted text³ and will appear at the bottom of the page.

Markdown:

This is a paragraph with multiple footnotes[^1]. We can add explanatory notes[^2] throughout the content. 

[^1]: This is the first footnote with a simple explanation.
[^2]: The second footnote with multiple paragraphs.
    
    To have multiple paragraphs, indent.

Tables

Tables are created using pipes and hyphens, see below for the markdown:

| Name     | Role      | Department  |
|----------|-----------|-------------|
| John     | Developer | Engineering |
| Sarah    | Designer  | Creative    |
| Michael  | Manager   | Operations  |

We can also align columns by adding colons to the header row:

| Left-aligned | Center-aligned | Right-aligned |
|:-------------|:-------------:|-------------:|
| Left         | Center        | Right        |
| Text         | Text          | Text         |

Table of Contents

Mono provides a built-in table of contents (ToC) shown on the side of the page for easy navigation through long posts.

To add a table of contents to a post, simply add showToC: true to the front matter:

---
title: "Your Post Title"
date: 2025-03-10
showToC: true
---

This generates an automatically structured table of contents based on the headings in the content. The generated ToC is responsive and includes all heading levels with proper indentation to indicate the content hierarchy (see side bar or the top for mobile view).

Customizing the ToC Display: We can control when the ToC appears by setting a threshold for minimum heading count in the site configuration:

# config.toml
[params.toc]
  enable = true
  minHeadings = 4  # Only show ToC if page has at least 4 headings

We can also customize the ToC title and depth in the configuration:

[params.toc]
  title = "On this page"  # Default is "Table of Contents"
  maxDepth = 3            # Only include h1-h3 headings (default is 4)

Math Rendering

The Mono theme includes built-in support for mathematical notation using KaTeX, allowing us to include complex equations and formulas in our content.

Inline Math: For inline mathematical expressions, use single dollar signs:

The formula for the area of a circle is $A = \pi r^2$.

This renders as: The formula for the area of a circle is $A = \pi r^2$.

Block Math: For larger, standalone equations, use double dollar signs:

$$
\begin{aligned}
\frac{\partial f}{\partial x} &= 2x + y \\
\frac{\partial f}{\partial y} &= x + 2y
\end{aligned}
$$

This renders as:

$$ \begin{aligned} \frac{\partial f}{\partial x} &= 2x + y \ \frac{\partial f}{\partial y} &= x + 2y \end{aligned} $$

Complex Mathematical Notation: KaTeX supports a wide range of mathematical notation, including:

• Fractions: $\frac{numerator}{denominator}$
• Summations: $\sum_{i=1}^{n} x_i$
• Integrals: $\int_{a}^{b} f(x) dx$
• Matrices: $\begin{pmatrix} a & b \ c & d \end{pmatrix}$
• Greek letters: $\alpha, \beta, \gamma, \Delta, \Omega$
• And much more

Example of a complex equation:

$$ \begin{aligned} S &= \sum_{i=1}^{n} \int_{a}^{b} f_i(x) dx \ &= \int_{a}^{b} \left( \sum_{i=1}^{n} f_i(x) \right) dx \end{aligned} $$

Enabling Math Rendering: Math rendering is enabled by default in the Mono theme. If we need to disable it for performance reasons on pages that don’t use mathematical notation, we can do so in the site configuration:

[params]
  math = false  # Set to true to enable globally

We can also enable it on a per-page basis in the front matter:

---
title: "Post with Math"
math: true  # Enable math rendering for this post only
---

Shortcodes

The Mono theme includes custom shortcodes for creating special content boxes such as asides, info boxes, warnings, and notes.

A Side Note

In case we’d like to add some side note or tangential information to the main text, we can use the aside shortcode: this contains some tangential information A helpful note with additional context.

This is how its markdown looks:

{{< aside "Aside Title" >}}
Things like live programming in a running system are incredibly valuable for a discovery programmer.
{{< /aside >}}

Special Content Boxes

Mono also provides shortcodes for different types of content boxes to highlight important information, mainly note, info, warning, and aside boxes:

All of these can be created using the following markdown syntax:

{{< note >}}
Content here.
{{< /note >}}

{{< info >}}
Content here.
{{< /info >}}

{{< warning >}}
Content here.
{{< /warning >}}

For each one of these boxes, we can also use a custom title instead and pass it as a parameter:

{{< warning "Custom Title" >}}
Content here.
{{< /warning >}}

Dropdown Notes

The Mono theme provides a dropdown note feature for content that might be initially hidden and expanded on demand:

{{< details >}}
Hidden content here.
{{< /details >}}

Similarily to special content boxes, we can use a custom summary title by passing it as a parameter:

{{< details "Click to expand" >}}
Hidden content here.
{{< /details >}}

This renders as:

Dropdown notes are useful for FAQs, supplementary information, or content that might be relevant to only some readers.