Shortcodes

Shortcodes are reusable HTML components you can call from inside markdown. They're Go templates stored in _shortcodes/. See Layouts for the template variables available to shortcodes via {{ .Page }}.

Creating a shortcode

Create _shortcodes/note.html:

<div role="alert"{{ if .Get "type" }} data-variant="{{ .Get "type" }}"{{ end }}>
{{ .Inner }}
</div>

Using shortcodes

Block shortcodes

Wrap content between opening and closing tags:

{{</* note type="warning" */>}}
This is a **warning** message. Markdown works inside.
{{</* /note */>}}

Result:

This is a warning message. Markdown works inside.

Self-closing shortcodes

For shortcodes without inner content:

{{</* badge text="New" type="success" /*/>}}

Result: New

Shortcode context

Templates receive a ShortcodeContext with:

Field Description
{{ .Inner }} Rendered inner content (markdown → HTML)
{{ .Get "key" }} Get a named argument
{{ .Args }} Map of all arguments
{{ .Page }} Parent page's template data
{{ .Page.Pages }} All non-draft pages available to the current page
{{ .SectionPages "guide" }} Pages in a section, excluding the current page

Examples

Note / alert

_shortcodes/note.html:

<div role="alert"{{ if .Get "type" }} data-variant="{{ .Get "type" }}"{{ end }}>
{{ .Inner }}
</div>

This is an info note. Good for tips and context.

Watch out — this is a warning.

Something went wrong. This is an error alert.

Section listing

_shortcodes/listing.html:

<ul>
{{ range .SectionPages (.Get "section") }}
  <li>
    <a href="{{ .URL }}">{{ .Title }}</a>
    {{ if .Date }}<small> — {{ .Date }}</small>{{ end }}
  </li>
{{ end }}
</ul>

Use it from markdown:

{{</* listing section="guide" /*/>}}

Pass an empty section or omit it to list all pages.

Collapsible details

_shortcodes/details.html:

<details{{ if .Get "open" }} open{{ end }}>
<summary>{{ .Get "summary" }}</summary>
{{ .Inner }}
</details>
Click to expand

This content is hidden by default. Markdown renders here too.

  • Item one
  • Item two
  • Item three
Another section

This one starts open because of open="true".

Processing order

  1. Parse frontmatter from markdown source
  2. Find and extract shortcode calls
  3. Render inner content of block shortcodes as markdown
  4. Execute shortcode templates with rendered inner + arguments
  5. Splice shortcode output back into the document
  6. Render the full document as markdown

This means shortcode output becomes part of the markdown document — you can mix shortcodes and markdown freely. Wiki links inside block shortcode content are resolved the same way as normal page content.

Syntax reference

Block:         {{</* name key="value" */>}}...content...{{</* /name */>}}
Self-closing:  {{</* name key="value" /*/>}}
Arguments:     key="value" pairs (quoted strings only)