Callouts
> [!NOTE] blockquotes without shortcodes.A callout is a GitHub / Obsidian style blockquote. Put > [!TYPE] on the first line and the body below it.
Use callouts to separate prerequisites, warnings, and asides from prose. If a prose sentence is sufficient, a callout is unnecessary.
Shortest form
Hugo Modules need Go on the machine; an offline archive does not.
If you omit the title, the callout uses the localized type name: “Note” in English or 「注意」 in Chinese. GitHub displays the source as a GitHub callout. Other Markdown readers display a plain blockquote. All content remains available.
Ten types
The first five types match GitHub. OINK adds five semantic types. Each type has a default icon and accent color.
hugo server -D previews drafts.
The floor is Hugo Extended 0.168.0; anything older fails the build outright.
hugo --cleanDestinationDir empties public/.
The first build after deleting resources/_gen is much slower.
Build passed with reviewed warnings — ship it.
Never commit go.work.
Should the site have comments? See enabling comments.
pgsty.com is a documentation site built from callouts and tables alone.
Documentation is a love letter that you write to your future self.
Type names are case-insensitive.
Custom title
Text after the marker on the same line becomes the title. It accepts inline Markdown, including code, bold text, and links.
public/Check that baseURL points at the production domain before a production
build, or every absolute link will be wrong.
Body content
The body uses page-level Markdown. It can contain lists, fenced code, tables, images, and nested callouts.
Start every line with >, including fence lines.
- Clone:
git clone https://github.com/pgsty/oink-starter my-docs - Enter the directory and preview:
- Open http://localhost:1313/
| Port | Purpose |
|---|---|
| 1313 | Hugo development server |
Collapsing
A - after the type makes the callout initially closed. A + makes it initially open.
Both use native <details> and load no JavaScript. Use them for full command output, alternatives, or background information that can remain hidden initially.
Why is Go needed?
Hugo downloads themes through Go’s module system (hugo mod get). A submodule
or an offline archive works without Go installed.
Open by default, but the reader can close it
The closed state is not remembered; a reload returns to the default.
The neutral disclosure, DETAILS
[!DETAILS] is a disclosure without a semantic color. It is closed by default; [!DETAILS]+ is open.
Use it for long output, complete configuration files, or other content that must be collapsible.
Full hugo version output
Custom icon
To replace the default icon, put {icon="fa-solid fa-xxx"} after the blockquote. Use one Font Awesome class pair.
The attribute line must immediately follow the blockquote, with no blank line between them.
Pigsty v4 installs PostgreSQL 18 by default.
Nesting
To nest callouts, add one > per level. Callouts can also appear inside list items or steps.
One nesting level is sufficient.
A theme version bump can change how a page renders.
How to back up
git tag pre-upgrade is enough — rolling back is git checkout pre-upgrade.
Unknown types and common slips
Unknown type names do not fail the build or remove content. The block renders as an ordinary blockquote with its [!TYPE] marker visible.
[!NOTICE] Not a valid type
The marker stays on the page to tell you so.
Other common problems:
- Formatters such as Prettier can merge titles into the body. Keep an empty
>line below the title to prevent this. - Formatters can move attribute lines. Wrap marker lines such as
{icon=…}in<!-- prettier-ignore-start -->/<!-- prettier-ignore-end -->. style,onclick, and unsupported attributes warn and are ignored. The attribute line accepts onlyiconandclass. See the table below.
Output
| Output | Shape |
|---|---|
| HTML | Static types are <div class="td-callout" role="note">; collapsible types are a native <details> + <summary> |
All static and expanded; disclosures carry a data-td-callout-collapsible marker |
|
| Markdown | The source blockquote is preserved, [!TYPE] marker and title included |
| RSS | Same as print — static and expanded |
Callouts load no script.
Parameter reference
The marker line > [!TYPE]± Title:
The attribute line {…}, immediately after the blockquote:
style, on*, and other keys warn and are ignored.
Limits
- Colors cannot be customized. The type sets the color. If you need a new meaning, choose the nearest type and write a title.
- The collapsed state is not saved.
- Callouts work inside
{.steps}list items and{{% steps %}}steps. See Steps. Start every blockquote line with>and align it with the list item’s indentation.
Related
- Steps — callouts inside a procedure
- Tabs — the same note split per platform
- Writing pages — when to use a callout and when to use prose