Shortcode reference

Every shortcode the basic theme ships, with syntax and a live example. Most take either positional or named params — never both mixed in the same call (a Hugo restriction, not this theme’s).

Repo & package cards

github, gitlab, huggingface, npm, crates, pypi all render the same .repo-card component. Each fetches live metadata from the relevant API at build time and falls back to a bare link card if the fetch fails — pass the override params to skip the network call entirely.

github

{{< github "owner/repo" >}}
{{< github "owner/repo" desc="…" lang="…" stars="…" >}}

gitlab

{{< gitlab "namespace/project" >}}
{{< gitlab "namespace/project" desc="…" stars="…" forks="…" >}}

huggingface

{{< huggingface "owner/model" >}}
{{< huggingface "owner/model" type="dataset" >}}
{{< huggingface "owner/model" desc="…" likes="…" downloads="…" >}}

npm

{{< npm "package-name" >}}
{{< npm "package-name" desc="…" version="…" license="…" >}}

crates

{{< crates "crate-name" >}}
{{< crates "crate-name" desc="…" version="…" downloads="…" >}}

pypi

{{< pypi "package-name" >}}
{{< pypi "package-name" desc="…" version="…" license="…" >}}

Code & content embeds

code

Imports a local file or a remote URL instead of pasting code inline, so it never drifts out of sync with the source. Optional lines="12-34" (1-indexed, inclusive) and lang= (guessed from the extension otherwise).

{{< code file="path/relative/to/project" >}}
{{< code url="https://raw.githubusercontent.com/…" lang="go" >}}
{{< code file="assets/js/console.js" lines="1-8" >}}

/* basic — a small floating terminal. No deps. Hidden until the launcher opens it;
   the page works fine without it. */
(function () {
  "use strict";

  // ---- pure core (side-effect-free so `node console.js` can self-check) ----

  function parse(input) {

gist

Hugo’s built-in gist shortcode was removed in v0.156. This one fetches the gist via the GitHub API and renders it with the theme’s own Chroma highlighting instead of GitHub’s unstyled <script> embed.

{{< gist "user" "gist-id" >}}

class HelloWorld
   def initialize(name)
      @name = name.capitalize
   end
   def sayHi
      puts "Hello #{@name}!"
   end
end

hello = HelloWorld.new("World")
hello.sayHi

bluesky

Fetches a post via Bluesky’s public AppView API — no auth needed. There’s no equivalent tweet shortcode: X/Twitter removed unauthenticated read access, so embedding one would require baking a developer API key into a public theme.

{{< bluesky "https://bsky.app/profile/<handle>/post/<id>" >}}

youtube

Hugo’s own built-in shortcode — no theme code needed, just a CSS rule so it matches the theme’s rounded corners.

{{< youtube VIDEO_ID >}}

Content helpers

swatches

A row of colour chips, each labelled with the value passed. No network.

{{< swatches "#hex1" "#hex2" "#hex3" >}}

admonition

type is one of note (default), tip, warning, danger. title defaults to the type, title-cased.

{{< admonition >}}Plain note.{{< /admonition >}}
{{< admonition type="warning" title="Careful" >}}…{{< /admonition >}}

details

Wraps the native <details>/<summary> disclosure — no JS.

{{< details summary="Click to expand" >}}Markdown content.{{< /details >}}

badge

An inline pill. color is optional — one of the pop palette names (red, orange, yellow, green, cyan, blue, purple, pink); omit it for a neutral badge.

{{< badge "MIT" >}}
{{< badge "v1.2.0" "blue" >}}

MIT v1.2.0 beta

mailto

An obfuscated mail link with an optional subject and link text. HTML entity-encoding alone doesn’t survive Hugo’s --minify pass (it decodes entities straight back to plaintext), so the real address is base64’d into data attributes and assembled by a few lines of inline JS on load — the one shortcode in the theme that needs JS. Params are positional-only (email, subject, text) since Hugo shortcodes can’t mix positional and named params in one call.

{{< mailto "user@example.com" >}}
{{< mailto "user@example.com" "Subject line" "link text" >}}

Questions? .

Footnotes

Not a shortcode — goldmark handles [^1] natively. The theme just adds CSS to match the mono/muted aesthetic.

A claim.[^1]

[^1]: The footnote.

A claim.¹