GoCalf Calf 的自留地 · 昙花一现
由 AI 生成

Shortcode reference

All theme shortcode arguments are named. Unknown options, wrong types and unsafe paths diagnose. Quote literal numeric strings; booleans are true/false, not quoted. Use outer % for standalone containers, nested < for containers inside containers, and < for every self-contained leaf. See composition. Escaped examples below are text, not live provider calls.

Containers

Common optional class / id strings use safe ASCII tokens (letter/underscore, then letters/digits/underscore/hyphen; classes may be space separated). No style, HTML, event handler, SVG or executable argument. Colors: red, orange, yellow, green, cyan, blue, purple, pink and neutral. These are adaptive Sidera families, not CSS keyword values; see content colors. child permits empty or codeblock; it adjusts presentation, not inclusion behavior.

ShortcodeArguments and defaults
blockcommon class/id only
foldingrequired nonblank title (inline Markdown); open=false; color=neutral; child=''
boxtitle=’’ (inline Markdown); color=neutral; child=''
gridcolumns integer 1–6 OR min_width integer 64–720 pixels; mutually exclusive; default auto-fill minimum 240px
cellcommon class/id only; immediate grid parent required
timelinecommon class/id only; one or more direct events, whitespace only between
eventrequired nonblank literal string title; common class/id; immediate timeline parent
tabsactive=1 (one-based integer within tab count); align=start/center/end; label=localized “Content tabs”; common class/id
tabrequired nonblank literal title; common class/id; immediate tabs parent

Grid takes only cells/whitespace, at least one cell. Tabs takes only direct tabs and whitespace, at least one tab. Tab bodies use the same single Markdown pass as other containers; nesting tabs inside a tab, box, fold or grid cell is supported. Blocks in labels fail. Container bodies retain native headings, links, alerts, math and fences in one Markdown pass. No arbitrary plugin nesting or automatic fold-heading behavior is promised.

Small leaves and cards

ShortcodeArguments and defaults
kbdrequired nonblank literal text
markrequired literal text; color=yellow (the same nine named families as containers)
urequired literal text; no whitespace is inserted around output
iconrequired name from the built-in/site icons registry; optional palette color; label=’’ (decorative)
hashtagrequired literal text; href=’’ (non-link chip); color=blue
blur / pswrequired literal text; cosmetic blur or concealment, revealable by hover/focus/touch
emp / wavy / del / sup / subrequired literal text; emphasis dots, wave underline, deletion, superscript, subscript
tiprequired literal text for the annotation; paired body for noninteractive inline Markdown
downloadrequired current-page bundle src; name=source basename; text=download filename
code-inlinepaired nonblank single-line code body; lang=text; unknown lexer falls back to plain text
quotrequired literal text; ornament=true
copyrequired literal text; prefix=’’ (not copied)
linkrequired href/text; icon=link (empty hides); image=’’, alt=''

kbd, mark, u, icon, hashtag, all text decorations, tip, download and code-inline are inline. Other leaves are block calls on their own lines. Text is escaped, not interpreted Markdown. Link destinations reuse exact source Page/resource resolution or safe local/HTTP(S)/mailto URLs; no remote metadata fetch. image takes visual priority over a named icon; alt defaults to decorative empty and is invalid without an image. Local/HTTP(S) images are browser-loaded, not rehosted/fetched at build time. Icons=false does not hide content artwork.

Inline controls and attachments

icon uses the same validated SVG registry as theme UI: built-in names or site data/icons.yaml entries. No image URLs, raw SVG or style argument. Omitted color inherits surrounding text; explicit color uses a Sidera family. Use label when the icon conveys meaning on its own. Authored icons remain visible with icons=false; the decorative icon on a download link does not.

hashtag accepts the same safe destinations as link, using href consistently. Omitting href produces a noninteractive chip, not an empty anchor. Colors do not cycle across builds. sup and sub always inherit the surrounding text color.

tip is an annotation, not a callout. Write text="Explanation" and put the term between opening/closing shortcodes; its body may contain emphasis, inline code or math, but not links, controls, images or blocks. Hover/focus/click shows the bubble; Escape dismisses it when enhanced. Without JavaScript, hover/focus still shows it.

blur and psw are not password protection or redaction. Their source text is public and available to assistive technology. Hover previews; click/Enter/Space reveals or conceals. Without JavaScript, focus reveals. Printing reveals the text, tab panels and annotations. Never put a real password or secret in these components.

download only publishes an existing native page-bundle attachment. src may contain subdirectories, spaces and Unicode; traversal, encoded paths, globs, absolute paths and URLs reject. A content Page is not an attachment. Optional name is a single filename (not a path); labels are literal escaped text. Bytes are unchanged; no remote fetching, file execution or platform-specific MIME logic. The browser controls whether the native download hint opens or saves the file.

code-inline trims surrounding whitespace and rejects line breaks. Interior spaces are retained through HTML minification, including in string literals. It reuses native Chroma and Sidera’s adaptive syntax colors, without block wrappers, line numbers, copy controls or configurable highlighter options. Use named lang, not the positional argument of older site-owned implementations. Site shortcodes still override theme shortcodes until the site owner deliberately removes the overrides.

Structured tables

rich-table is a paired < leaf with YAML/JSON body, or a bodyless {{< rich-table src="table.yaml" />}} call. It supports Markdown cells, multi-row headers and rectangular row/column spans within header or body sections.

ArgumentContract
srcOptional exact current-page .yaml / .yml / .json resource; excludes inline body
captionOptional literal caption below the table, centered like other figure captions; empty suppresses it
labelNonblank scroll-region label; localized default; caption takes precedence
bordersrows (default) or grid; grid adds subtle vertical separators at actual cell boundaries
cellwidthDefault per-column minimum: integer 32–720px, default 140
row_headersBoolean, default false; cells starting in the first body column become row headers
sticky_headerBoolean, default false; pins the complete header inside a bounded scroll region
sticky_first_columnBoolean, default false; first-column cells must have colspan=1
max_heightOptional integer 160–1200px; defaults to 480 with sticky_header, otherwise unbounded
class / idCommon safe tokens

The data object accepts headers, required rows, and optional columns. Strings are Markdown cells; objects add text, rowspan, colspan, align, and body-only header: row / data. Omit slots covered by rowspans; empty strings are real cells. Header-to-body rowspans, overlapping rectangles and holes diagnose. See structured tables for the schema, examples, accessibility, print behavior and size limits.

Images

text
{{< image src="thumbnail.jpg" original="original.jpg" alt="A useful description" width=320 >}}

Required strings: src and explicit alt (empty for decorative). Optional strings: original='', background (transparent or hex only), caption, class/id; optional positive integer pixel width/height; loading=lazy or eager (default lazy, async decoding). Caption omitted follows auto_caption/alt; explicit text overrides, empty or no-caption suppresses. No arbitrary CSS, processing, cropping or artwork rewriting.

Src/original independently resolve exact native bundle/cross-bundle/assets or same-site/HTTP(S) image URLs. Unsafe schemes/protocol-relative/traversal reject. Original enables a native-link thumbnail plus progressive modal zoom/pan/download; no request for a distinct original until opened, no gallery/editor/automatic retry. No-JS opens original directly. Download is a native anchor: cross-origin policies may open rather than save. Alt/caption remain independent and escaped.

class="invert-when-dark invert-soft" applies the optional soft visual conversion to the image, not its caption; the expanded original preserves that effect. See image inversion classes.

Code resources

snippet argumentContract
srcRequired exact resource key
scopepage (default), or shared under assets/snippets/
from / toPositive inclusive line bounds; omitted first/last; no clamp
titleBasename default; explicit nonblank plain string
langExtension default; empty/text is plain text; unknown lexer falls back to text
optionsComma-separated supported native highlighter options below

Supported options: linenos=true/false/inline/table; linenumbersintable=true/false; linenostart=positive integer; hl_lines=selection-relative positions/ranges; anchorlinenos=true/false; lineanchors=safe unique prefix. Defaults start numbering at the first selected source line. No inline/wrapper/data override option. At site config level use native lineNos=true and lineNumbersInTable=false for inline numbers; lineNos=‘inline’ is not accepted there on the verified Hugo version.

Full downloads preserve complete original bytes; selection/copy is not redaction. Only valid text resources, not arbitrary filesystem/network input or execution. Read code resources for exact line-ending/publication rules.

Media and badges

ShortcodeArguments and supported input
videorequired src: current-page MP4 key or explicit HTTP(S) MP4; width optional integer 1–8192; title optional nonblank literal; disabled=false
diagramsnetrequired src: exact current-page .drawio resource; optional nonblank literal caption
badge_githubrequired string user/repo; branch optional string; release=false; disabled=false

Video attaches media only on Load video and never auto-plays; no-JS retains file link. Drawio is a local one-page uncompressed viewer, not an editor or arbitrary stencil loader. Badge images automatically contact Shields when enabled; disabled keeps only the repository link. Provider reliability and media codecs remain external limits. No diagram title/disabled aliases are accepted. Native Mermaid is a fence, not a shortcode; only caption/class/id attributes are supported. Read diagrams, video and badges before enabling them.

Interactive charts

echarts accepts either an inline JSON body or an exact current-page .json src, plus optional .json data. Both forms share the native echarts fence renderer. Use {{< echarts src="chart.json" />}} for a bodyless shortcode; /> is required. Optional caption is nonblank plain text; height is 200–1200 pixels (default 360); safe class/id tokens are supported. No title, disabled, remote URL, CSV, YAML or JavaScript callback aliases. Line, bar, pie/donut and scatter charts stay interactive in local sandboxed frames, with source viewing and a self-contained JSON download. Read interactive charts for examples, dataset conflicts, option boundaries, accessibility and CSP requirements.

JSX tools (opt-in)

jsx accepts a module body or an exact page-bundle src ending in .jsx. Optional arguments are css, title, caption, fallback, appearance (plain by default, or card), mode (page by default, or sandbox) and sandbox height (160–1200 pixels, default 280). Title is a plain-text label above the component; caption is plain text below. Neither is required. Plain appearance has no outer border, background or padding; appearance is independent of execution mode. Bodyless calls use />. Requires the site’s explicit params.jsx = true; unlike snippet, this compiles executable JavaScript. See Interactive JSX for imports, trust and fallbacks.

Overrides

Hugo-native site shortcode/render-hook overrides win normally. Nested leaf overrides must retain components/leaf.html; blockquote hooks must retain the private-node branch, and link hooks the sidera-inline: branch. Examples are the shipped thin wrappers. Never treat author HTML or resource bytes as trusted output. Contributor entry points and tests live in repository AGENTS.md, not this manual’s content tree.