自用 Hugo Blox 語法整理

Welcome 👋

我在這邊整理了 Hugo Blox 的基本語法，包含 Hugo Blox 內建的用法，也包含自定義元件、 Shortcode 的用法。

Shortcode 範例

表單

自建 Shortcode- Form

目錄 Table of Contents

內建 Shortcode- TOC

Code

{{< toc mobile_only=true is_open=true >}}

Demo

自定義 Shortcode-TOC

Universal Announcement

雷達圖

自定義 Callouts

Callouts

Callout 是 Hugo Blox 的特色之一，可以參考 Hugo Blox 官方文件 有一些 icon 是沒有的，需要自己匯入，我是把 icon 的路徑放在 assets/media/icons/hero/ 裡面。

Note

Tip

Warning

Charts 圖表類

Hugo Blox is designed to give technical content creators a seamless experience. You can focus on the content and Hugo Blox handles the rest.

Use popular tools such as Plotly, Mermaid, and data frames.

Hugo Blox supports the popular Plotly format for interactive data visualizations. With Plotly, you can design almost any kind of visualization you can imagine!

Save your Plotly JSON in your page folder, for example line-chart.json, and then add the {{< chart data="line-chart" >}} shortcode where you would like the chart to appear.

Demo

You might also find the Plotly JSON Editor useful.

Diagrams

Hugo Blox supports the Mermaid Markdown extension for diagrams.

An example flowchart:

```mermaid
graph TD
A[Hard] -->|Text| B(Round)
B --> C{Decision}
C -->|One| D[Result 1]
C -->|Two| E[Result 2]
```

renders as

An example sequence diagram:

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

renders as

An example class diagram:

```mermaid
classDiagram
Class01 <|-- AveryLongClass : Cool
Class03 *-- Class04
Class05 o-- Class06
Class07 .. Class08
Class09 --> C2 : Where am i?
Class09 --* C3
Class09 --|> Class07
Class07 : equals()
Class07 : Object[] elementData
Class01 : size()
Class01 : int chimp
Class01 : int gorilla
Class08 <--> C2: Cool label
```

renders as

An example state diagram:

```mermaid
stateDiagram
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
```

renders as

Data Frames

Save your spreadsheet as a CSV file in your page’s folder and then render it by adding the Table shortcode to your page:

{{< table path="results.csv" header="true" caption="Table 1: My results" >}}

renders as

Create a personal knowledge base and share your knowledge with your peers.

Hugo Blox web framework empowers you with one of the most flexible note-taking capabilities out there.

Create a powerful knowledge base that works on top of a local folder of plain text Markdown files.

Use it as your second brain, either publicly sharing your knowledge with your peers via your website, or via a private GitHub repository and password-protected site just for yourself.

Mindmaps

Hugo Blox supports a Markdown extension for mindmaps.

With this open format, can even edit your mindmaps in other popular tools such as Obsidian.

Simply insert a Markdown code block labelled as markmap and optionally set the height of the mindmap as shown in the example below.

Mindmaps can be created by simply writing the items as a Markdown list within the markmap code block, indenting each item to create as many sub-levels as you need:

```markmap {height="200px"}
- Hugo Modules
  - Hugo Blox
  - blox-plugins-netlify
  - blox-plugins-netlify-cms
  - blox-plugins-reveal
```

renders as

- Hugo Modules
  - Hugo Blox
  - blox-plugins-netlify
  - blox-plugins-netlify-cms
  - blox-plugins-reveal

Anh here’s a more advanced mindmap with formatting, code blocks, and math:

```markmap
- Mindmaps
  - Links
    - [Hugo Blox Docs](https://docs.hugoblox.com/)
    - [Discord Community](https://discord.gg/z8wNYzb)
    - [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
  - Features
    - Markdown formatting
    - **inline** ~~text~~ *styles*
    - multiline
      text
    - `inline code`
    -
      ```js
      console.log('hello');
      console.log('code block');
      ```
    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$
```

renders as

- Mindmaps
  - Links
    - [Hugo Blox Docs](https://docs.hugoblox.com/)
    - [Discord Community](https://discord.gg/z8wNYzb)
    - [GitHub](https://github.com/HugoBlox/hugo-blox-builder)
  - Features
    - Markdown formatting
    - **inline** ~~text~~ *styles*
    - multiline
      text
    - `inline code`
    -
      ```js
      console.log('hello');
      console.log('code block');
      ```
    - Math: $x = {-b \pm \sqrt{b^2-4ac} \over 2a}$

文字類

Highlighting

Highlight important text with mark:

<mark>Highlighted text</mark>

隱藏-防劇透

Provide a simple yet fun self-assessment by revealing the solutions to challenges with the spoiler shortcode:

{{< spoiler text="👉 Click to view the solution" >}}
You found me!
{{< /spoiler >}}

renders as

Code

Hugo Blox Builder utilises Hugo’s Markdown extension for highlighting code syntax. The code theme can be selected in the config/_default/params.yaml file.

```python
import pandas as pd
data = pd.read_csv("data.csv")
data.head()
```

renders as

import pandas as pd
data = pd.read_csv("data.csv")
data.head()

Inline Images

{{< icon name="python" >}} Python

renders as

Python

Callouts

Use callouts (aka asides, hints, or alerts) to draw attention to notes, tips, and warnings.

By wrapping a paragraph in {{% callout note %}} ... {{% /callout %}}, it will render as an aside.

{{% callout note %}}
A Markdown aside is useful for displaying notices, hints, or definitions to your readers.
{{% /callout %}}

Demo

Or use the warning callout type so your readers don’t miss critical details:

嵌入媒體檔案

Embed videos, podcasts, code, LaTeX math, and even test students!

On this page, you’ll find some examples of the types of technical content that can be rendered with Hugo Blox.

Video

Teach your course by sharing videos with your students. Choose from one of the following approaches:

內建-Youtube:

{{< youtube D2vj0WcvH5c >}}

Demo

內建-Bilibili:

{{< bilibili BV1WV4y1r7DF >}}

Demo

內建-影片檔

Videos may be added to a page by either placing them in your assets/media/ media library or in your page’s folder, and then embedding them with the video shortcode:

{{< video src="my_video.mp4" controls="yes" >}}

內建-MP3 檔

You can add a podcast or music to a page by placing the MP3 file in the page’s folder or the media library folder and then embedding the audio on your page with the audio shortcode:

{{< audio src="ambient-piano.mp3" >}}

Demo

Math

Hugo Blox Builder supports a Markdown extension for $\LaTeX$ math. Enable math by setting the math: true option in your page’s front matter, or enable math for your entire site by toggling math in your config/_default/params.yaml file:

features:
  math:
    enable: true

To render inline or block math, wrap your LaTeX math with $...$ or $$...$$, respectively.

Example math block:

$$
\gamma_{n} = \frac{ \left | \left (\mathbf x_{n} - \mathbf x_{n-1} \right )^T \left [\nabla F (\mathbf x_{n}) - \nabla F (\mathbf x_{n-1}) \right ] \right |}{\left \|\nabla F(\mathbf{x}_{n}) - \nabla F(\mathbf{x}_{n-1}) \right \|^2}
$$

renders as

Example inline math $\nabla F(\mathbf{x}_{n})$ renders as $\nabla F(\mathbf{x}_{n})$.

Example multi-line math using the math linebreak (\\):

$$f(k;p_{0}^{*}) = \begin{cases}p_{0}^{*} & \text{if }k=1, \\
1-p_{0}^{*} & \text{if }k=0.\end{cases}$$

renders as