Extended Markdown Syntax

FixIt theme has some extended syntax elements for you to write articles.

Emoji Support

This part is shown in the emoji support page.

Mathematical Formula

FixIt theme supports mathematical formulas based on $\KaTeX$.

Set the property enable = true under [params.math] in your theme configuration and the property math: true of the article front matter to enable the automatic rendering of mathematical formulas.

Note

Since Hugo generates HTML documents according to the syntax such as _/*/>> when rendering Markdown documents, and some text content in the form of escape characters (such as \(/\)/\[/\]/\\) escape processing will be performed automatically, therefore, additional escape character expressions are required for these places to achieve automatic rendering:

  • _ -> \_
  • * -> \*
  • >> -> \>>
  • \( -> \\(
  • \) -> \\)
  • \[ -> \\[
  • \] -> \\]
  • \\ -> \\\\

FixIt theme supports [raw shortcode][raw-shortcode] to avoid these escape characters, which helps you write raw mathematical formula content.

Example raw input:

1
2
3
4
5
6
{{< raw >}}Inline Formula: \(\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots\){{< /raw >}}

{{< raw >}}
Block Formula:
\[ a=b+c \\ d+e=f \]
{{< /raw >}}

The rendered output looks like this:

Inline Formula: \(\mathbf{E}=\sum_{i} \mathbf{E}_{i}=\mathbf{E}_{1}+\mathbf{E}_{2}+\mathbf{E}_{3}+\cdots\)
Block Formula: \[ a=b+c \\ d+e=f \]

Inline Formula

The default inline delimiters are:

  • $ ... $
  • \( ... \) (escaped: \\( ... \\))

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 looks like this:

$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 Formula

The default block delimiters are:

  • $$ ... $$
  • \[ ... \] (escaped: \\[ ... \\])
  • \begin{equation} ... \end{equation} (unnumbered: \begin{equation*} ... \end{equation*})
  • \begin{align} ... \end{align} (unnumbered: \begin{align*} ... \end{align*})
  • \begin{alignat} ... \end{alignat} (unnumbered: \begin{alignat*} ... \end{alignat*})
  • \begin{gather} ... \end{gather} (unnumbered: \begin{gather*} ... \end{gather*})
  • \begin{CD} ... \end{CD}
Warning
When there are newlines in the block formula, please turn on goldmark.renderer.hardWraps carefully, set it to true, Goldmark will render the newlines as <br> elements.

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
$$ 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 looks like this:

$$ 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}

Tip
You can add more inline and block delimiters in your theme configuration.

Copy-tex

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

By the extension, when selecting and copying $\KaTeX$ rendered elements, copies their $\LaTeX$ source to the clipboard.

Set the property copyTex = true under [params.math] in your theme configuration to enable Copy-tex.

Select and copy the formula rendered in the previous section, and you can find that the copied content is the LaTeX source code.

mhchem

mhchem is an extension for $\KaTeX$.

By the extension, you can write beautiful chemical equations easily in the article.

Set the property mhchem = true under [params.math] in your theme configuration to enable mhchem.

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

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

The rendered output looks like this:

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

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

Ruby Annotation

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

1
[Hugo]^(An open-source static site generator)

The rendered output looks like this:

HugoAn open-source static site generator

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

90/100

Font Awesome

FixIt theme uses Font Awesome 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 😂

Tip
This is related to an issue for Hugo, which has not been resolved.

Another example is:

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

The rendered output looks like this:

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

Custom attribute

The premise is that you set goldmark.parser.attribute.block to true.

Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets ({.myclass class="class1 class2"}) and placing it after the Markdown element it decorates, on the same line for titles and on a new line directly below for blocks.

Hugo supports adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.

A blockquote with a CSS class:

1
2
3
> foo  
> bar
{.text-danger}

The rendered output looks like this:

foo
bar

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

Note that attributes in code fences must come after the opening tag, with any other highlighting processing instruction, e.g.:

1
2
3
```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```

Code Fences Extended

Code Block Attributes

You can add attributes to a code block, for example:

1
2
3
```js {title="test.js"}
console.log('hello FixIt!');
```

The rendered output looks like this:

1
console.log('hello FixIt!');

Currently supported attributes include:

  • title: The title of the code block.

Diagrams Support

This part is shown in the diagrams support page.

Buy me a coffee~
Alipay
WeChat Pay
0%