diff --git a/projects/hugo/hugo_shortcodes.md b/projects/hugo/hugo_shortcodes.md deleted file mode 100644 index 418bf46..0000000 --- a/projects/hugo/hugo_shortcodes.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -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 **`{{}}`** 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*/}}
Your HTML here
{{/* /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):** `{{}}` -* **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:** -* ❌ `{{< /* shortcode */ >}}` (Spaces around the comment markers cause parsing errors or unrecognized characters) -* ❌ `{{/*< shortcode >*/}}` (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](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. | - ---- \ No newline at end of file