Hugo Theme Stack

Image Gallery

Mon, 26 Jan 2026 00:00:00 +0000

Stack theme has a built-in support for image galleries. It allows you to create a beautiful gallery by simply placing multiple images side-by-side.

Sample Gallery

How it works

The gallery is powered by Photoswipe and a custom internal script. It automatically calculates the best layout for your images based on their aspect ratios.

To create a gallery, you just need to put multiple images in the same line (or paragraph).

Syntax

1
2
3

![Image 1](image1.jpg)  ![Image 2](image2.jpg)

![Image 3](image3.jpg)  ![Image 4](image4.jpg)

Note: There should be two spaces between the images to ensure they stay in the same line in Markdown

Gallery Syntax inspired by Typlog

Shortcodes

Mon, 26 Jan 2026 00:00:00 +0000

Stack theme also provides some custom shortcodes to enhance your content.

Quote

The quote shortcode allows you to display a quote with an author, source, and URL.

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
― A famous person, The book they wrote

Usage

1
2
3

{{< quote author="Author Name" source="Source Title" url="https://example.com" >}}
Quote content here.
{{< /quote >}}

Video

The video shortcode allows you to embed self-hosted or remote video files.

Your browser doesn't support HTML5 video. Here is a link to the video instead.

Usage

`1`	`{{< video src="https://example.com/video.mp4" >}}`

Bilibili

Embed videos from Bilibili. Supports both av and bv IDs.

Usage

`1`	`{{< bilibili "BV1634y1t7xR" >}}`

YouTube

Hugo’s built-in YouTube shortcode.

Usage

`1`	`{{< youtube ZJthWmvUzzc >}}`

Tencent Video

Embed videos from Tencent Video.

Usage

`1`	`{{< tencent "u00306ng962" >}}`

GitLab Snippet

Embed snippets from GitLab.

Usage

`1`	`{{< gitlab 2349278 >}}`

Diagrams

Stack supports Mermaid diagrams out of the box.

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Usage

Wrap your Mermaid code in a code block with the language set to mermaid.

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

Math Typesetting

Sat, 24 Jan 2026 00:00:00 +0000

The Stack theme supports rendering mathematical notation using KaTeX.

Enabling KaTeX

Per-page basis

To enable KaTeX for a specific post, include math: true in the post’s frontmatter:

---
title: "My Math Post"
math: true
---

Globally

To enable KaTeX for all posts, set article.math to true in your site configuration (params.yaml or params.toml):

1
2

article:
    math: true

Examples

Inline Math

You can include math inline by wrapping the expression in single dollar signs $.

For example: $ \varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887… $ renders as $ \varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887… $

Block Math

For larger equations, use double dollar signs $$ to create a math block.

$$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$

More Complex Formula

$$ f(a) = \frac{1}{2\pi i} \oint_\gamma \frac{f(z)}{z-a} dz $$

Note: For a full list of supported TeX functions, refer to the KaTeX documentation.

Mermaid Diagrams

Tue, 23 Dec 2025 00:00:00 +0000

This theme supports Mermaid diagrams directly in your Markdown content. Mermaid lets you create diagrams and visualizations using text and code.

About Mermaid.js

This theme integrates Mermaid.js (v11) to render diagrams from text definitions within Markdown code blocks. Mermaid is a JavaScript-based diagramming and charting tool that uses text-based syntax inspired by Markdown.

For complete syntax documentation, see the Mermaid.js documentation.

Getting Started

To create a Mermaid diagram, simply use a fenced code block with mermaid as the language identifier:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

The diagram will be automatically rendered when the page loads.

Features

Auto-detection: Mermaid script only loads on pages that contain diagrams
Theme Support: Diagrams automatically adapt to light/dark mode
HTML Labels: Support for HTML content in labels (like <br/> for line breaks)
Configurable: Customize version, security level, and more in your site config

Configuration

You can configure Mermaid in your site config:

hugo.yaml:

params:
  article:
    mermaid:
      version: "11"           # Mermaid version from CDN
      look: classic           # classic or handDrawn (sketch style)
      lightTheme: default     # Theme for light mode
      darkTheme: neutral      # Theme for dark mode
      securityLevel: strict   # strict (default), loose, antiscript, sandbox
      htmlLabels: true        # Enable HTML in labels

hugo.toml:

[params.article.mermaid]
  version = "11"           # Mermaid version from CDN
  look = "classic"         # classic or handDrawn (sketch style)
  lightTheme = "default"   # Theme for light mode
  darkTheme = "neutral"    # Theme for dark mode
  securityLevel = "strict" # strict (default), loose, antiscript, sandbox
  htmlLabels = true        # Enable HTML in labels

Additional Global Options

These optional settings use Mermaid’s defaults when not specified:

hugo.yaml:

params:
  article:
    mermaid:
      maxTextSize: 50000      # Maximum text size (default: 50000)
      maxEdges: 500           # Maximum edges allowed (default: 500)
      fontSize: 16            # Global font size in pixels (default: 16)
      fontFamily: "arial"     # Global font family
      curve: "basis"          # Line curve: basis, cardinal, linear (default: basis)
      logLevel: 5             # Debug level 0-5, 0=debug, 5=fatal (default: 5)

hugo.toml:

[params.article.mermaid]
  maxTextSize = 50000      # Maximum text size (default: 50000)
  maxEdges = 500           # Maximum edges allowed (default: 500)
  fontSize = 16            # Global font size in pixels (default: 16)
  fontFamily = "arial"     # Global font family
  curve = "basis"          # Line curve: basis, cardinal, linear (default: basis)
  logLevel = 5             # Debug level 0-5, 0=debug, 5=fatal (default: 5)

For diagram-specific options (like flowchart.useMaxWidth), use Mermaid’s init directive directly in your diagram:

```mermaid
%%{init: {'flowchart': {'useMaxWidth': false}}}%%
flowchart LR
    A --> B
```

Security Note: The default securityLevel: strict is recommended. Set to loose only if you need HTML labels like <br/> in your diagrams.

Available Themes

Theme	Description
`default`	Standard colorful theme
`neutral`	Grayscale, great for printing and dark mode
`dark`	Designed for dark backgrounds
`forest`	Green color palette
`base`	Minimal theme, customizable with themeVariables
`null`	Disable theming entirely

Custom Theme Variables

For full control, use the base theme with custom variables:

hugo.yaml:

params:
  article:
    mermaid:
      lightTheme: base
      darkTheme: base
      lightThemeVariables:
        primaryColor: "#4a90d9"
        primaryTextColor: "#ffffff"
        lineColor: "#333333"
      darkThemeVariables:
        primaryColor: "#6ab0f3"
        primaryTextColor: "#ffffff"
        lineColor: "#cccccc"
        background: "#1a1a2e"

hugo.toml:

[params.article.mermaid]
  lightTheme = "base"
  darkTheme = "base"

  [params.article.mermaid.lightThemeVariables]
    primaryColor = "#4a90d9"
    primaryTextColor = "#ffffff"
    lineColor = "#333333"

  [params.article.mermaid.darkThemeVariables]
    primaryColor = "#6ab0f3"
    primaryTextColor = "#ffffff"
    lineColor = "#cccccc"
    background = "#1a1a2e"

Common variables: primaryColor, secondaryColor, tertiaryColor, primaryTextColor, lineColor, background, fontFamily

Note: Theme variables only work with the base theme and must use hex color values (e.g., #ff0000).

Diagram Types

Flowchart

Flowcharts are the most common diagram type. Use graph or flowchart with direction indicators:

TD or TB: Top to bottom
BT: Bottom to top
LR: Left to right
RL: Right to left

flowchart LR
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Sequence Diagram

Perfect for showing interactions between components:

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts 
prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!

Class Diagram

Visualize class structures and relationships:

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    class Fish{
        -int sizeInFeet
        -canEat()
    }
    class Zebra{
        +bool is_wild
        +run()
    }

State Diagram

Model state machines and transitions:

stateDiagram-v2
    [*] --> Still
    Still --> [*]

    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]

Entity Relationship Diagram

Document database schemas:

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER {
        int orderNumber
        string deliveryAddress
    }

Gantt Chart

Plan and track project schedules:

gantt
    title A Gantt Diagram
    dateFormat YYYY-MM-DD
    section Section
        A task          :a1, 2024-01-01, 30d
        Another task    :after a1, 20d
    section Another
        Task in Another :2024-01-12, 12d
        another task    :24d

Pie Chart

Display proportional data:

pie showData
    title Key elements in Product X
    "Calcium" : 42.96
    "Potassium" : 50.05
    "Magnesium" : 10.01
    "Iron" :  5

Git Graph

Visualize Git branching strategies:

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    commit

Mindmap

Create hierarchical mindmaps:

mindmap
  root((mindmap))
    Origins
      Long history
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness
and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

Timeline

Display chronological events:

timeline
    title History of Social Media Platform
    2002 : LinkedIn
    2004 : Facebook
         : Google
    2005 : YouTube
    2006 : Twitter

Advanced Features

HTML in Labels

To use HTML in labels, you must set securityLevel: loose in your site config:

hugo.yaml:

params:
  article:
    mermaid:
      securityLevel: loose
      htmlLabels: true

hugo.toml:

1
2
3

[params.article.mermaid]
  securityLevel = "loose"
  htmlLabels = true

Then you can use HTML tags like <br/> for line breaks:

```mermaid
graph TD
    A[Line 1<br/>Line 2] --> B[<b>Bold</b> text]
```

Per-Diagram Theming

Override the theme for a specific diagram using Mermaid’s frontmatter:

```mermaid
%%{init: {'theme': 'forest'}}%%
graph TD
    A[Start] --> B[End]
```

%%{init: {'theme': 'forest'}}%%
graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[Car]

Inline Styling with `style`

You can style individual nodes directly within your diagram using the style directive:

```mermaid
flowchart LR
    A[Start] --> B[Process] --> C[End]
    style A fill:#4ade80,stroke:#166534,color:#000
    style B fill:#60a5fa,stroke:#1e40af,color:#000
    style C fill:#f87171,stroke:#991b1b,color:#fff
```

Result:

flowchart LR
    A[Start] --> B[Process] --> C[End]
    style A fill:#4ade80,stroke:#166534,color:#000
    style B fill:#60a5fa,stroke:#1e40af,color:#000
    style C fill:#f87171,stroke:#991b1b,color:#fff

Style properties include:

fill - Background color
stroke - Border color
stroke-width - Border thickness
color - Text color
stroke-dasharray - Dashed border (e.g., 5 5)

Styling with CSS Classes

You can define reusable styles with classDef and apply them using :::className:

```mermaid
flowchart LR
    A:::success --> B:::info --> C:::warning
    classDef success fill:#4ade80,stroke:#166534,color:#000
    classDef info fill:#60a5fa,stroke:#1e40af,color:#000
    classDef warning fill:#fbbf24,stroke:#92400e,color:#000
```

Result:

flowchart LR
    A:::success --> B:::info --> C:::warning
    classDef success fill:#4ade80,stroke:#166534,color:#000
    classDef info fill:#60a5fa,stroke:#1e40af,color:#000
    classDef warning fill:#fbbf24,stroke:#92400e,color:#000

Subgraphs

Group related nodes together:

flowchart TB
    subgraph one
        a1-->a2
    end
    subgraph two
        b1-->b2
    end
    subgraph three
        c1-->c2
    end
    one --> two
    three --> two
    two --> c2

Theme Switching

This theme automatically detects your site’s light/dark mode preference and adjusts the Mermaid diagram theme accordingly:

Light mode: Uses the default Mermaid theme
Dark mode: Uses the dark Mermaid theme (configurable)

Try toggling the theme switcher to see diagrams update in real-time!

Complex Example

Here’s an example with subgraphs, HTML labels, emojis, and custom styling:

flowchart TD
  subgraph client["👤 Client"]
      A["User Device
192.168.1.10"]
  end

  subgraph cloud["☁️ Cloud Gateway"]
      B["Load Balancer
(SSL Termination)"]
  end

  subgraph server["🖥️ Application Server"]
      C["API Gateway
10.0.0.1"]
      D["Auth Service
10.0.0.2"]
      E["Web Server
10.0.0.3"]
      F["Database
10.0.0.4"]
  end

  A -- "HTTPS Request" --> B
  B -- "Forward
(internal)" --> C
  C -- "Authenticate" --> D
  D -- "Token" --> C
  C -- "Route" --> E
  E --> F

  style client fill:#1a365d,stroke:#2c5282,color:#fff
  style cloud fill:#f6ad55,stroke:#dd6b20,color:#000
  style server fill:#276749,stroke:#22543d,color:#fff

Note: This example requires securityLevel: loose for HTML labels and styling to work.

Known Limitations

Dark Mode Theming

Mermaid.js’s built-in themes have some limitations:

dark theme (default): Best text contrast, but some diagram backgrounds may appear brownish (e.g., Gantt charts)
neutral theme: Better background colors, but some text (labels, legends) may have reduced contrast

For full control, use the base theme with custom variables:

hugo.yaml:

params:
  article:
    mermaid:
      darkTheme: base
      darkThemeVariables:
        primaryColor: "#1f2937"
        primaryTextColor: "#ffffff"
        lineColor: "#9ca3af"
        textColor: "#e5e7eb"

hugo.toml:

[params.article.mermaid]
  darkTheme = "base"

  [params.article.mermaid.darkThemeVariables]
    primaryColor = "#1f2937"
    primaryTextColor = "#ffffff"
    lineColor = "#9ca3af"
    textColor = "#e5e7eb"

We plan to improve dark mode theming in future updates as Mermaid.js evolves.

Troubleshooting

Diagram not rendering?

Make sure you’re using a fenced code block with mermaid as the language
Check your browser’s console for syntax errors
Verify your Mermaid syntax at Mermaid Live Editor

HTML not working in labels?

HTML in labels requires securityLevel: loose. Update your configuration:

hugo.yaml:

params:
  article:
    mermaid:
      securityLevel: loose
      htmlLabels: true

hugo.toml:

1
2
3

[params.article.mermaid]
  securityLevel = "loose"
  htmlLabels = true

Warning: Using loose security level allows HTML in diagrams. Only use this if you trust your diagram content.

Syntax errors?

Mermaid is strict about syntax. Common issues:

Missing spaces around arrows
Unclosed brackets or quotes
Invalid node IDs (avoid special characters)

Resources

Mermaid Documentation
Mermaid Live Editor - Test diagrams interactively
Mermaid Syntax Reference

Mon, 01 Jan 0001 00:00:00 +0000

-–

title: 我的第一篇文章 date: 2026-01-25 description: Sample article showcasing basic Markdown syntax and formatting for HTML elements. tags:

markdown
css
html
themes categories:
Documentation image: pawel-czerwinski-8uZPynIu-rQ-unsplash.jpg

This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

Headings

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

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[^1]

[^1]: The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015.

Blockquote with alert

📝 Note

Highlights information that users should take into account, even when skimming.

📝 Custom title

You can also provide a custom title for the note alert.

💡 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.

Tables

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

Name	Age
Bob	27
Alice	23

Inline Markdown within tables

Italics	Bold	Code
italics	bold	`code`

A	B	C	D	E	F
Lorem ipsum dolor sit amet, consectetur adipiscing elit.	Phasellus ultricies, sapien non euismod aliquam, dui ligula tincidunt odio, at accumsan nulla sapien eget ex.	Proin eleifend dictum ipsum, non euismod ipsum pulvinar et. Vivamus sollicitudin, quam in pulvinar aliquam, metus elit pretium purus	Proin sit amet velit nec enim imperdiet vehicula.	Ut bibendum vestibulum quam, eu egestas turpis gravida nec	Sed scelerisque nec turpis vel viverra. Vivamus vitae pretium sapien

Code Blocks

Code block with backticks

<!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> Example HTML5 Document

Test

Diff code block

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

One line code block

`1`	`<p>A paragraph</p>`

List Types

Ordered List

First item
Second item
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.

Hugo Theme Stack

Image Gallery

Sample Gallery

How it works

Syntax

Shortcodes

Quote

Usage

Video

Usage

Bilibili

Usage

YouTube

Usage

Tencent Video

Usage

GitLab Snippet

Usage

Diagrams

Usage

Math Typesetting

Enabling KaTeX

Per-page basis

Globally

Examples

Inline Math

Block Math

More Complex Formula

Mermaid Diagrams

About Mermaid.js

Getting Started

Features

Configuration

Additional Global Options

Available Themes

Custom Theme Variables

Diagram Types

Flowchart

Sequence Diagram

Class Diagram

State Diagram

Entity Relationship Diagram

Gantt Chart

Pie Chart

Git Graph

Mindmap

Timeline

Advanced Features

HTML in Labels

Per-Diagram Theming

Inline Styling with style

Styling with CSS Classes

Subgraphs

Theme Switching

Complex Example

Known Limitations

Dark Mode Theming

Troubleshooting

Diagram not rendering?

HTML not working in labels?

Syntax errors?

Resources

Headings

H3

H4

H5

H6

Paragraph

Blockquotes

Blockquote without attribution

Blockquote with attribution

Blockquote with alert

Tables

Inline Markdown within tables

Code Blocks

Code block with backticks

Code block indented with four spaces

Diff code block

One line code block

List Types

Inline Styling with `style`