---
author: wompmacho
tags: []
title: Hugo Special Markdown Codes
description: Available Shortcodes, and other resources for configuration.
date: '2025-03-27'
lastmod: '2025-03-28'
---

## 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**
    ```markdown
    {{%/* 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:
    ````markdown
    ```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 `&#123;&#123;% %&#125;&#125;` 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)
*   ❌ `&#123;&#123;` (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](https://blowfish.page/docs/shortcodes/).

*   **`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](https://github.com/orgs/community/discussions/16925).

### Basic Syntax

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

### Foldable Callouts

Use `+` for expanded by default or `-` for collapsed.
```markdown
> [!TYPE]+ Foldable Title
> This callout is expanded by default.
```

### Supported Types

The following types are mapped to specific icons and colors:

| Type        | Icon            | Description                               |
| :---------- | :-------------- | :---------------------------------------- |
| `note`      | Pen             | General information (default).            |
| `abstract`  | Lines           | Summaries or abstracts.                   |
| `info`      | Info Circle     | Informational notes.                      |
| `tip`       | Lightbulb       | Helpful tips or suggestions.              |
| `success`   | Check Circle    | Successful outcomes or "done" states.     |
| `question`  | Question Circle | Questions or areas needing clarification. |
| `warning`   | Triangle Excl.  | Warnings to pay attention to.             |
| `failure`   | X Circle        | Failed outcomes.                          |
| `danger`    | Triangle Excl.  | Critical warnings.                        |
| `bug`       | Bug             | Known issues or bugs.                     |
| `example`   | Teacher         | Examples and use cases.                   |
| `quote`     | Quote           | Important quotes.                         |
| `important` | Excl. Circle    | Critical information.                     |
| `caution`   | Triangle Excl.  | Use with caution.                         |
| `todo`      | List Check      | Tasks or items to be done.                |
| `hint`      | Lightbulb       | Hints or clues.                           |

---