Extended Markdown Syntax

This article shows the FixIt Flavored Markdown extended syntax.

Alerts

Also known as callouts or admonitions, alerts are blockquotes used to emphasize critical information.

Basic syntax

With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets.

An example of all five types:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

> [!NOTE]
> Highlights information that users should take into account, even when skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Crucial information necessary for users to succeed.

> [!WARNING]
> Critical content demanding immediate user attention due to potential risks.

> [!CAUTION]
> Negative potential consequences of an action.

The rendered output looks like this:

Extended syntax

With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of + or -, typically used to indicate whether an alert is graphically foldable.

Change the title

By default, the title of the alert is its type identifier in title case. You can change it by adding text after the type identifier:

1
2

> [!NOTE] FixIt
> A Clean, Elegant but Advanced Hugo Theme.

You can even omit the body to create title-only alerts:

1

> [!TIP] Title-only alert

Foldable Alerts

You can make a Alert foldable by adding a plus (+) or a minus (-) directly after the type identifier.

1
2
3
4
5

> [!WARNING]+ Radiation hazard
> Do not approach or handle without protective gear.

> [!QUESTION]- Are Alerts foldable?
> Yes! In a foldable Alert, the contents are hidden when collapsed.

Nested Alerts

You can nest alerts in multiple levels.

1
2
3

> [!question] Can alerts be nested?
> > [!todo] Yes!, they can.
> > > [!example] You can even use multiple layers of nesting.

Content-only Alerts

You can create content-only alerts by adding a tilde (~) directly after the type identifier.

1
2

> [!TIP]~
> This is a content-only alert without a title.

Supported types

The extended alert syntax supports 13 types of admonition banners, Unless you Customize admonitions, any unsupported type defaults to the note type. The type identifier is case-insensitive.

The complete examples are as follows:

> [!note]+
> The quick brown fox jumps over the lazy dog.

> [!abstract]-
> The quick brown fox jumps over the lazy dog.

> [!info]-
> The quick brown fox jumps over the lazy dog.

Todo

> [!todo]-
> The quick brown fox jumps over the lazy dog.

> [!tip]-
> The quick brown fox jumps over the lazy dog.

> [!success]-
> The quick brown fox jumps over the lazy dog.

> [!question]-
> The quick brown fox jumps over the lazy dog.

> [!warning]-
> The quick brown fox jumps over the lazy dog.

> [!failure]-
> The quick brown fox jumps over the lazy dog.

> [!danger]-
> The quick brown fox jumps over the lazy dog.

> [!bug]-
> The quick brown fox jumps over the lazy dog.

> [!example]-
> The quick brown fox jumps over the lazy dog.

> [!quote]-
> The quick brown fox jumps over the lazy dog.

Color Preview

In Content, you can call out colors within a sentence by using backticks. A supported color model within backticks will display a visualization of the color.

1

The background color is `#ffffff` for light mode and `#000000` for dark mode.

The background color is #ffffff for light mode and #000000 for dark mode.

Here are the currently supported color models.

Task lists

To create a task list, start each list item with a hyphen and space followed by [ ].

1
2

- [x] This is a completed task.
- [ ] This is an incomplete task.

The rendered output looks like this:

• This is a completed task.
• This is an incomplete task.

You can use any character inside the brackets to mark it as completed or otherwise.

1
2
3
4
5
6
7
8

- [ ] Unchecked
- [x] Checked
- [/] In Progress
- [-] Cancelled
- [<] Scheduled
- [>] Rescheduled
- [!] Important
- [?] Question

The rendered output looks like this:

• Unchecked
• Checked
• In Progress
• Cancelled
• Scheduled
• Rescheduled
• Important
• Question

Inserted Text

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

[markup]

[markup.goldmark]

[markup.goldmark.extensions]
strikethrough = false

# https://gohugo.io/configuration/markup/#extras
[markup.goldmark.extensions.extras]

[markup.goldmark.extensions.extras.delete]
enable = true

[markup.goldmark.extensions.extras.insert]
enable = true

[markup.goldmark.extensions.extras.mark]
enable = true

[markup.goldmark.extensions.extras.subscript]
enable = true

[markup.goldmark.extensions.extras.superscript]
enable = true

Hugo supports an inserted text Markdown extension:

1

The author of FixIt theme is ++Lruihao++.

The rendered output looks like this:

The author of FixIt theme is Lruihao.

Marked Text

Hugo supports a marked text Markdown extension:

1

==FixIt== is an awesome Hugo theme!

The rendered output looks like this:

FixIt is an awesome Hugo theme!

The extended marked text syntax supports 6 types of Marked Text.

1
2
3
4
5
6

==Primary==[primary]
==Secondary==[secondary]
==Success==[success]
==Info==[info]
==Warning==[warning]
==Danger==[danger]

The rendered output looks like this:

Primary Secondary Success Info Warning Danger

Unless you customize marked text, any unsupported type defaults to the default type.

1

==This is a custom type with pink color.==[pink]

Customize the marked text by adding the following CSS in your project directory assets/scss/custom.scss:

1
2
3

.mark-pink {
  --fi-mark-background-color: pink;
}

The rendered output looks like this:

This is a custom type with pink color.

The HTML looks like this:

1

<mark class="mark-pink">This is a custom type with pink color.</mark>

Subscript

Hugo supports a subscript Markdown extension:

1

The chemical formula of water is H~2~O.

The rendered output looks like this:

The chemical formula of water is H₂O.

Superscript

Hugo supports a superscript Markdown extension:

1

2^10^ equals 1024.

The rendered output looks like this:

2¹⁰ equals 1024.

Emoji Support

This part is shown in the emoji support page.

Mathematical Formulas

FixIt supports mathematical formulas using $\KaTeX$ or $\text{MathJax}$, with $\KaTeX$ as the default engine.

You can modify the automatic rendering configuration for mathematical formulas in the theme configuration:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97

[markup]

[markup.goldmark]

[markup.goldmark.extensions]

[markup.goldmark.extensions.passthrough]
enable = true

[markup.goldmark.extensions.passthrough.delimiters]
block = [
  [
    '\[',
    '\]'
  ],
  [
    '$$',
    '$$'
  ]
]
inline = [
  [
    '\(',
    '\)'
  ],
  [
    '$',
    '$'
  ]
]

[params]

[params.page]

[params.math]
enable = true
# mathematical formulas rendering engines, optional values: ["katex", "mathjax"]
type = "katex"

# KaTeX server-side rendering (https://katex.org)
# KaTeX partial config: https://gohugo.io/functions/transform/tomath/#options
[params.math.katex]
# KaTeX extension copy-tex
copy_tex = true
throw_on_error = false
error_color = "#ff4949"

# custom macros map
# syntax: <macro> = <definition>
[params.math.katex.macros]
# "\\f" = "#1f(#2)" # usage: $\f{a}{b}$

# MathJax server-side rendering (https://www.mathjax.org)
# MathJax config: https://docs.mathjax.org/en/latest/options/index.html
[params.math.mathjax]
cdn = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"

[params.math.mathjax.packages]
# "[+]" = ['configmacros']

# custom macros map
# syntax: <macro> = <definition>
[params.math.mathjax.macros]
# "bold" = ["{\\bf #1}", 1] # usage: $\bold{math}$

[params.math.mathjax.loader]
load = [ "ui/safe" ]

[params.math.mathjax.loader.paths]
# custom = "https://cdn.jsdelivr.net/gh/sonoisa/XyJax-v3@3.0.1/build/"

# more loader config e.g source, dependencies, provides etc.

[params.math.mathjax.options]
enable_menu = true
# HTML tags that won't be searched for math
skip_html_tags = [
  "script",
  "noscript",
  "style",
  "textarea",
  "pre",
  "code",
  "math",
  "select",
  "option",
  "mjx-container"
]
# class that marks tags not to search
ignore_html_class = "mathjax_ignore"

# HTML tags that can appear within math
[params.math.mathjax.options.include_html_tags]
# "#comment" = ""
# br = "\n"
# wbr = ""

KaTeX

$\KaTeX$ uses Hugo’s transform.ToMath function for server-side rendering, resulting in faster client-side loading.

Inline Formulas

The default delimiters for inline formulas are:

• $ ... $
• \( ... \)

For example:

1

$c = \pm\sqrt{a^2 + b^2}$ and \(f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi\)

The rendered output is as follows:

$c = \pm\sqrt{a^2 + b^2}$ and $f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi$

Block Formulas

The default delimiters for formula blocks are:

• $$ ... $$
• \[ ... \]

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

$$ c = \pm\sqrt{a^2 + b^2} $$

\[f(x)=\int_{-\infty}^{\infty} \hat{f}(\xi) e^{2 \pi i \xi x} d \xi\]

$$
\begin{equation*}
  \rho \frac{\mathrm{D} \mathbf{v}}{\mathrm{D} t}=\nabla \cdot \mathbb{P}+\rho \mathbf{f}
\end{equation*}
$$

$$
\begin{equation}
  \mathbf{E}=\sum_{i} \mathbf{E}\_{i}=\mathbf{E}\_{1}+\mathbf{E}\_{2}+\mathbf{E}_{3}+\cdots
\end{equation}
$$

$$
\begin{align}
  a&=b+c \\
  d+e&=f
\end{align}
$$

$$
\begin{alignat}{2}
   10&x+&3&y = 2 \\
   3&x+&13&y = 4
\end{alignat}
$$

$$
\begin{gather}
   a=b \\
   e=b+c
\end{gather}
$$

$$
\begin{CD}
   A @>a>> B \\
@VbVV @AAcA \\
   C @= D
\end{CD}
$$

The rendered output is as follows:

Copying Formulas

Copy-tex is an extension of $\KaTeX$.

With this extension, when you select and copy a $\KaTeX$-rendered formula, its $\LaTeX$ source code will be copied to the clipboard.

Enable Copy-tex by setting the copy_tex attribute to true under [params.math.katex] in your theme configuration.

Select and copy the rendered formulas from the previous section, and you will find that the copied content is the $\LaTeX$ source code.

Chemical Equations

mhchem is an extension of $\KaTeX$, providing the \ce and \pu functions.

With this extension, you can easily write beautiful chemical equations in your articles.

1
2
3
4
5

$$ \ce{CO2 + C -> 2 CO} $$

$$ \ce{Hg^2+ ->[I-] HgI2 ->[I-] [Hg^{II}I4]^2-} $$

$$C_p[\ce{H2O(l)}] = \pu{75.3 J // mol K}$$

The rendered output is as follows:

Custom Macros

You can add custom macros in your theme configuration under [params.math.katex.macros].

For example:

1
2

[params.math.katex.macros]
"\\f" = "#1f(#2)" # usage: $\f{a}{b}$

Then use it in your articles as follows:

1
2
3
4
5

$$
\f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi
$$

The rendered output is as follows:

Error Messages

If an error occurs while rendering a formula, $\KaTeX$ will display an error message on the page.

For example:

1

$c = \pm\sqrt{a\^2 + b^2}$

The rendered output is as follows. Hovering the mouse over the error message will display detailed error information:

c = \pm\sqrt{a\^2 + b^2}

MathJax

$\text{MathJax}$ performs client-side rendering using JavaScript after the page is loaded. It is slower but more powerful.

This part is introduced on the MathJax Support page.

Ruby Annotation

An extended Markdown syntax for ruby annotation is supported in FixIt theme:

1

[FixIt]^(A Clean, Elegant but Advanced Hugo Theme)

The rendered output looks like this:

FixItA Clean, Elegant but Advanced Hugo Theme

Fraction

An extended Markdown syntax for fraction is supported in FixIt theme:

1
2
3

[Light]/[Dark]

[99]/[100]

The rendered output looks like this:

^Light/_Dark

⁹⁰/₁₀₀

Font Awesome

FixIt theme uses Font Awesome V6 as the icon library. You can easily use these icons in your articles.

Get the class of icons you wanted from the Font Awesome website.

1
2
3

Gone camping! :(fa-solid fa-campground fa-fw): Be back soon.

That is so funny! :(fa-regular fa-grin-tears):

The rendered output looks like this:

Gone camping!  Be back soon.

That is so funny!

Escape character

In some special cases (when writing this theme documentation ), your content will conflict with basic or extended Markdown syntax, and it is inevitable.

The escape character syntax can help you build the content you wanted:

1

{?X} -> X

For example, two : will enable emoji syntax, which is not the behavior you want. The escape character syntax is like this:

1

{?:}joy:

The rendered output looks like this:

:joy: instead of 😂

Another example is:

1

[link{?]}(#escape-character)

The rendered output looks like this:

[link](#escape-character) instead of link.

Markdown attributes

Update your site configuration to enable Markdown attributes for block-level elements.

Hugo supports Markdown attributes on images and block elements including blockquotes, fenced code blocks, headings, horizontal rules, lists, paragraphs, and tables.

Syntax

1
2

some Markdown content
{#id .class1 .class2 key1="value1" key2="value2"}

In most cases, place the attribute list beneath the markup element. For headings and fenced code blocks, place the attribute list on the right.

Examples

horizontal rule

A horizontal rule with a CSS class:

1
2

---
{.awesome-hr}

The rendered output looks like this:

blockquote

A blockquote with a CSS class:

1
2

> The quick brown fox jumps over the lazy dog.
{.blockquote-center}

The rendered output looks like this:

The quick brown fox jumps over the lazy dog.

table & list

There are some current limitations: For tables you can currently only apply it to the full table, and for lists the ul/ol-nodes only, e.g.:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

* Fruit
  * Apple
  * Orange
  * Banana
  {.text-success}
* Dairy
  * Milk
  * Cheese
  {.text-warning}
{.text-primary}

The rendered output looks like this:

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

Code Fences Extended

FixIt theme extends the standard Markdown code fences to support advanced features including diagrams, charts, and interactive visualizations. These extended code fences enable you to create rich, dynamic content directly within your Markdown files.

Syntax

The extended code fences use the same triple backtick syntax as standard Markdown, but with specific language identifiers that trigger special rendering engines:

1
2
3

```LANG [OPTIONS]
// Enter content specific to the language here
```

Languages

These features are automatically enabled in FixIt theme and require no additional configuration. Simply use the appropriate language identifier in your code fence, and the content will be rendered using the corresponding engine.

GoAT

goat ASCII art diagrams that render as scalable vector graphics.

Mermaid

mermaid Professional diagrams including flowcharts, sequence diagrams, and more.

ECharts

echarts Interactive data visualization charts and graphs.

Timeline

timeline Chronological event displays with rich formatting.

JSON

json Render JSON data structures with syntax highlighting and collapsible views.

File Tree

file-tree Render file and directory structures as interactive trees.

Toggle

toggle Renders syntax-highlighted configuration data in TOML, YAML, and JSON formats.

Options

You can supply extra options to the code block via Hugo syntax highlighting options, theme code block configuration, Markdown attributes or the following options:

Option	Description	Type
title	Code block title	string
name	Code block name or tab item name	string
group	Code block tabs group name	string
before_tabs	Content displayed before tab items	string
filename	Code block filename	string

For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

```vue {.line-wrapping, name="App.vue", title="Hello World", max_shown_lines=11, linenos=false, hl_lines=[4,"8-9"], shadow=hover}
<script setup>
import { ref } from 'vue'

const msg = ref('Hello World!')
</script>

<template>
  <h1>{{ msg }}</h1>
  <input v-model="msg" />
</template>

<style lang="scss" scoped>
</style>
```

The rendered output looks like this:

<script setup>
import { ref } from 'vue'

const msg = ref('Hello World!')
</script>

<template>
  <h1>{{ msg }}</h1>
  <input v-model="msg" />
</template>

<style lang="scss" scoped>
</style>

The group and name options can be used together to create tabbed code blocks. For example:

1
2
3
4
5
6
7

```python {group="languages", name="Hi Python"}
print('Hello, world!')
```
<!-- Use .active to set the default active tab -->
```js {group="languages", name="Hi JS", .active}
console.log('Hello, world!');
```

The rendered output looks like this:

1

print('Hello, world!')

1

console.log('Hello, world!')

Table Extended

FixIt theme extends standard Markdown tables with auto-numbering, client-side sorting, and caption support.

Auto Numbering

Enable auto table numbering in your theme configuration:

1
2

[params.table]
number = true

Tables will be automatically numbered as “Table 1”, “Table 2”, etc.

Sorting

Enable table sorting in your theme configuration:

1
2

[params.table]
sort = true

When enabled, all tables support client-side sorting by clicking on column headers. Click once for ascending, again for descending, and a third time to reset.

Caption

Add a caption to any table using Markdown attributes:

1
2
3
4
5

| Name  | Age | Score |
| :---- | --: | ----: |
| Alice |  25 |    90 |
| Bob   |  30 |    85 |
{caption="User Data"}

The caption will be displayed above the table with numbering (if enabled) separated by a dash.

Per-table Override

Enable or disable numbering and sorting for specific tables using Markdown attributes.

Disable numbering and sorting:

1
2
3
4

| Name  | Age |
| :---- | --: |
| Alice | 25  |
{number=true, sort=false}

The rendered output looks like this: