Hugo Special Markdown Codes

Available Shortcodes

#

Project Shortcodes

#

Custom shortcodes defined in layouts/shortcodes/.

• include: Inject the contents of external files into your page. Supports local Hugo content paths and absolute paths mounted from the host (e.g., /srv/configs/..., /srv/dev/hugo/wiki/...).

  CRITICAL: Angle Brackets (< >) vs. Percentage Signs (% %)

  • Use {{% include ... %}} when you want the included text to be parsed as Markdown. This is required when including other .md files so their headers, lists, and links render properly.
  • Use {{< include ... >}} to output the raw text directly without Markdown processing.

  Example 1: Including another Markdown file

  {{% include "/srv/dev/hugo/wiki/README.md" %}}

  Example 2: Including raw code into a Code Block Wrap the shortcode in standard Markdown code fences to syntax-highlight an external configuration file:

  ```yaml
  {{% include "/srv/configs/docker_compose/homepage/docker-compose.yaml" %}}
  ```

• video: Embed local or remote videos.

  • Usage: {{/* video src="path/to/video.mp4"*/}}

• rawhtml: Insert raw HTML content.

  • Usage: {{/* rawhtml*/}}<div>Your HTML here</div>{{/* /rawhtml*/}}

Escaping Shortcodes (For Documentation)

#

When writing documentation about shortcodes (or anytime you need to display &#123;&#123;< >&#125;&#125; or {{% %}} without Hugo executing them), you MUST use Hugo’s built-in comment syntax inside the delimiters.

The Rule: Place /* immediately after the opening delimiter, and */ immediately before the closing delimiter. No spaces are allowed between the delimiter and the comment marker.

• Correct (Angle Brackets): {{< shortcode_name >}}
• Correct (Percentage Signs): {{% shortcode_name %}}
• Correct (Inner only): {{/* shortcode_name */}} (If you just want to show the generic brackets without < > or % %)

Common Mistakes that break the build:

• ❌ &#123;&#123;< /* shortcode */ >&#125;&#125; (Spaces around the comment markers cause parsing errors or unrecognized characters)
• ❌ &#123;&#123;/*< shortcode >*/&#125;&#125; (Comment markers placed outside the inner delimiters)
• ❌ {{ (Using HTML entities is unnecessary, harder to read in source, and can break copy-pasting)

Theme Shortcodes (Blowfish)

#

Commonly used shortcodes from the Blowfish theme.

• alert: Display a callout/alert box.
  • Usage: {{/* alert icon="circle-info"*/}}Your message here.{{/* /alert*/}}
• badge: Display a small badge.
  • Usage: {{/* badge*/}}New{{/* /badge*/}}
• icon: Display an icon from the theme’s icon set.
  • Usage: {{/* icon "github"*/}}
• button: Create a styled button.
  • Usage: {{/* button href="https://google.com" target="_self"*/}}Click Me{{/* /button*/}}
• mermaid: Render Mermaid.js diagrams.
  • Usage: {{/* mermaid*/}}graph TD; A-->B;{{/* /mermaid*/}}
• timeline: Create a vertical timeline.
  • Usage: {{/* timeline*/}}{{/* timelineItem ...*/}}{{/* /timeline*/}}

Markdown Callouts (Admonitions)

#

We use hugo-admonitions which follows the GitHub/Obsidian alert syntax.

Basic Syntax

#

> [!TYPE] Title (Optional)
> Content here.

Foldable Callouts

#

Use + for expanded by default or - for collapsed.

> [!TYPE]+ Foldable Title
> This callout is expanded by default.

Supported Types

#

The following types are mapped to specific icons and colors: