Markdown Guide & Syntax

HugoBlox uses GitHub Flavored Markdown (GFM) with powerful extensions. This guide covers the essentials for writing content.

📝 Basic Formatting

Common syntax you’ll use every day.

Text

Description	Syntax	Result
Bold	**Bold**	Bold
Italic	*Italic*	Italic
Strikethrough	~~Strike~~	Strike
Subscript	<sub>Sub</sub>	Sub
Superscript	<sup>Super</sup>	Super
Underline	<ins>Underline</ins>	Underline
Code	`Code`	Code
Link	[Link](url)	Link

Lists

Unordered

- Item 1
- Item 2
  - Sub-item

• Item 1
• Item 2
  • Sub-item

Ordered

1. First
2. Second
3. Third

1. First
2. Second
3. Third

Task list

- [x] Done
- [ ] To Do

• Done
• To Do

Quotes

> This is a blockquote.
>
> It can span multiple lines.

This is a blockquote.

It can span multiple lines.

Tables

| Feature | Status |
| :--     | :--:   |
| Tabs    | ✅     |
| Math    | ✅     |

Feature	Status
Tabs	✅
Math	✅

Images

Basic syntax:

![Alt text](my-image.jpg "Optional title")

Rendered:

From site media library in assets/media/ (first checks for image in page folder):

![Wireframe](landing-page-wireframe.png "Wireframe")

HTML for sizing:

<img src="my-image.jpg" alt="Descriptive alt text" width="600" />

Link an image:

[![Alt text](my-image.jpg)](https://example.com)

🚨 Callouts (Asides)

Highlight critical information using GitHub-style callouts.

Syntax

> [!NOTE]
> Useful information.

> [!TIP]
> Helpful advice.

> [!WARNING]
> Urgent warning!

Preview

Note

Useful information.

Tip

Helpful advice.

Caution

Urgent warning!

提示

Prefer these standard Markdown callouts over the legacy {{< callout >}} shortcode for better portability.

💻 Code & Syntax Highlighting

Display code snippets with automatic highlighting.

```python {2}
def hello():
    print("Hello, world!")  # This line is highlighted!
```

For non-standard languages, you may need to enable them in your configuration.

📐 Math & Diagrams

Advanced rendering for technical content.

Math (KaTeX)

Inline: $E = mc^2$

Block:

$$
E = mc^2
$$

Math is auto-detected, but you can always force it to be parsed with the front matter: math: true.

Diagrams (Mermaid)

Create your diagram in your preferred Markdown editor or the online diagram editor.

```mermaid
graph TD;
  A[Start] --> B{Working?};
  B -- Yes --> C[Great];
  B -- No --> D[Debug];
```

🔌 Shortcodes

Shortcodes are special Hugo templates that insert rich components.

警告

Shortcodes are processed by Hugo, so they won’t render in non-Hugo Markdown viewers (like GitHub). Use standard Markdown where possible.

Content Components

Shortcode	Description	Example Input
Buttons	CTA links	{{< button url="/start/" >}}Get Started{{< /button >}}
Icons	SVG icons	{{< icon name="hero/rocket" >}}
Steps	Numbered lists	{{< steps >}} ... {{< /steps >}}
Spoilers	Collapsible details	{{< spoiler text="Click me" >}}Content{{< /spoiler >}}
TOC	In-page Table of Contents	{{< toc >}}

📓 Notebooks

Render Jupyter Notebooks (.ipynb) directly in your content. Preserves code, markdown, and rich outputs (plots, HTML, JSON).

Usage

Local File (in assets/notebooks/ or page bundle):

{{< notebook src="analysis.ipynb" >}}

Remote URL:

{{< notebook src="https://raw.githubusercontent.com/user/repo/main/demo.ipynb" >}}

Configuration

Option	Default	Description
src	-	Required Path to file or URL
title	filename	Custom header title
show_code	true	Show/hide input cells
show_outputs	true	Show/hide output cells
show_metadata	false	Show kernel info
line_numbers	false	Show code line numbers

提示

For the best experience, keep your notebooks in the same folder as your markdown file (Page Bundle). This makes src="notebook.ipynb" work instantly without path headaches.

Media Embeds

Use standard syntax for best compatibility, but shortcodes offer more control.

# Video with poster
{{< video src="demo.mp4" poster="thumb.jpg" >}}

# Audio player
{{< audio src="podcast.mp3" >}}

# YouTube/Vimeo/etc.
{{< embed src="https://www.youtube.com/watch?v=..." >}}

# Figure with caption
{{< figure src="image.jpg" caption="My Image" >}}

提示

Use Page Bundles (folders named index.md) so your media files (demo.mp4) can live right next to your content file.

🔗 Best Practices

• Relative Links: Use [Link](../page) instead of full URLs. This keeps links working in previews and forks.
• Asset Location: Keep images in assets/media/ for global use, or in the page bundle for page-specific use.
• Accessibility: Always add alt text to images: ![Alt text](image.jpg).