Markdown on Yaoyao Games

Markdown Syntax Guide

Sun, 25 Jan 2026 00:00:00 +0000

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¹

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>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>Example HTML5 Document</title>
</head>
<body>
 <p>Test</p>
</body>
</html>

Diff code block

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

One line code block

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

H2O

Xn + Yn = Zn

Press CTRL + ALT + Delete to end the session.

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

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎

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:

[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:

[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

Markdown on Yaoyao Games

Markdown Syntax Guide

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

Ordered List

Unordered List

Nested list

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

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

Inline Styling with `style`