Shortcodes on hugodoks

hint

Mon, 01 Jan 0001 00:00:00 +0000

hint renders a titled callout box with a Markdown body. Give the style alone, positionally, or the style and a title by name:

{{< hint warning >}}Something that can bite if ignored.{{< /hint >}}

{{< hint style="tip" title="Best practice" >}}The recommended way.{{< /hint >}}

Shortcode parameters are either all positional or all named, so a custom title needs style="…" too. Styles: info (default), note, tip, warning, danger, success; unknown styles fall back to info. The title defaults to the style’s name.

button

Mon, 01 Jan 0001 00:00:00 +0000

button renders a link as a Pico role="button" element. Named params: href, style (secondary or contrast), icon and the outline="true" flag. External links get rel="noopener" automatically.

Get started Back to the gallery hugodoks on GitHub

Source

{{< button href="../getting-started/" icon="rocket-launch" >}}Get started{{< /button >}}

{{< button href="../shortcodes/" style="secondary" outline="true" >}}Back to the gallery{{< /button >}}

{{< button href="https://github.com/fernandezvara/hugodoks" style="contrast" icon="code" >}}hugodoks on GitHub{{< /button >}}

pagelink

Mon, 01 Jan 0001 00:00:00 +0000

pagelink takes a content path (positional or page=) and renders a card with the target’s icon, title and description. Because it resolves through site.GetPage, a typo warns at build time instead of 404ing your readers.

Getting started

Install hugodoks in a new Hugo project and publish your first docs page.

Configuration

Site params, menus and build settings hugodoks understands.

Source

{{< pagelink "/docs/getting-started" >}}

{{< pagelink page="/docs/configuration" >}}

columns

Mon, 01 Jan 0001 00:00:00 +0000

columns wraps column children in Pico’s .grid — equal-width columns on desktop that stack under 768px.

Left column

Markdown works in here
Lists, code, other shortcodes

Middle column

Each column is an equal share of the row.

Right column

hugo server --bind 0.0.0.0

Source

{{< columns >}}
 {{< column >}}
 **Left column**
 {{< /column >}}
 {{< column >}}
 **Right column**
 {{< /column >}}
{{< /columns >}}

steps

Mon, 01 Jan 0001 00:00:00 +0000

steps wraps a Markdown ordered list and renders it with large accent step markers — use it for install procedures and tutorials.

Create the site — hugo new site my-docs
Add the theme — import github.com/fernandezvara/hugodoks as a Hugo module
Configure outputs — add searchindex to outputs.home
Write docs — pages under content/docs/ appear in the sidebar
Ship it — hugo --gc --minify

Source

{{< steps >}}
1. **Create the site** — `hugo new site my-docs`
2. **Add the theme** — import `github.com/fernandezvara/hugodoks`
{{< /steps >}}

tabs

Mon, 01 Jan 0001 00:00:00 +0000

tabs groups tab children into keyboard-accessible tabbed panels. Each tab takes its title as the first positional parameter (or title=). Panels hold any Markdown, including code blocks.

[module]
 [[module.imports]]
 path = "github.com/fernandezvara/hugodoks"

git submodule add https://github.com/fernandezvara/hugodoks themes/hugodoks

theme = "hugodoks"

docker run --rm -v "$PWD:/src" -w /src \
 docker.io/hugomods/hugo:exts hugo server --bind 0.0.0.0

Source

{{< tabs >}}
 {{< tab "Hugo module" >}}
 ```toml
 path = "github.com/fernandezvara/hugodoks"
 ```
 {{< /tab >}}
 {{< tab "Git submodule" >}}
 theme = "hugodoks"
 {{< /tab >}}
{{< /tabs >}}

annotated

Mon, 01 Jan 0001 00:00:00 +0000

annotated renders a code block with a numbered annotation list beneath it in a <figcaption>. Split code from notes with  — the ordered list becomes the caption.

[outputs]
 home = ["html", "rss", "searchindex"]

[markup.highlight]
 noClasses = false

searchindex emits /index.json, the data source for the search modal. Hugo never merges outputs from a theme — declare it yourself.
Class-based highlighting lets the theme’s light/dark code stylesheets apply; the default inline styles would ignore the theme toggle.

Source

{{< annotated >}}
```toml
noClasses = false
```
<!-- annotations -->
1. The note for this code.
2. Another note.
{{< /annotated >}}

types

Mon, 01 Jan 0001 00:00:00 +0000

types renders pipe-separated values as a row of code badges — for parameter signatures, front-matter reference tables and return types.

Accepted values for params.docs.repoBranch:

string "main" "develop"

A hint’s style positional parameter:

info warning danger success

Source

{{< types >}}string | "main" | "develop"{{< /types >}}

paramcallout

Mon, 01 Jan 0001 00:00:00 +0000

paramcallout renders its body as a linked callout only when the named site param is set — the link points at the param’s value. It’s the page-level counterpart of the landing banner’s only_when_param.

Use it for “a live demo is running” notes on pages that describe one: deploy previews inject the URL at build time, and the callout simply isn’t there in builds without it.

Info

Nothing rendered above? That’s the feature working: this build has no exampleurl param. Rebuild with HUGO_PARAMS_EXAMPLEURL="https://example.com" to see it — the theme’s own test suite asserts both cases.

Source

{{< paramcallout param="exampleurl" icon="squares-four" >}}
A live deployment was configured for this build — open it
{{< /paramcallout >}}

Named params: param (the site param to check, required) and icon.

icons

Mon, 01 Jan 0001 00:00:00 +0000

icons renders every glyph in the theme’s vendored Phosphor font (regular weight) with its name — no network needed. Use any name below wherever the theme accepts an icon:

icon: front matter — sidebar nav and section cards.
params.brand.icon — next to the site title.
params.docs.aiAssistIcon — the “Ask AI” dropdown button.
Shortcodes — icon parameter on button, pagelink, paramcallout; landing icon: fields.
Templates — {{ partial "hd-icon.html" "rocket-launch" }} renders <i class="ph ph-rocket-launch hd-icon">.

Unknown names render a blank glyph — there is no fallback.

Shortcodes on hugodoks

hint

button

Source#

pagelink

Source#

columns

Source#

steps

Source#

tabs

Source#

annotated

Source#

types

Source#

paramcallout

Source#

icons

Source

Source

Source

Source

Source

Source

Source

Source