wompmacho
0b70afc5eb
All checks were successful
deploy-docs / build-and-deploy (push) Successful in 49s
99 lines
4.2 KiB
Markdown
99 lines
4.2 KiB
Markdown
---
|
|
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*/}}`
|
|
|
|
### 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. |
|
|
|
|
--- |