docs-public/projects/hugo/hugo_shortcodes.md

author, tags, title, description, date, lastmod

author	tags	title	description	date	lastmod
wompmacho		Hugo Special Markdown Codes	Available Shortcodes, and other resources for configuration.	2025-03-27	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

  {{%/* 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 {{< >}} 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:

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.

---