Shortcode Formatting Examples

The Meshery documentation uses a variety of shortcodes to create rich, formatted content such as callouts, tabs, and generated tables.

This page is a visual reference for documentation contributors. It shows the markdown syntax required to invoke each shortcode, followed by its rendered output, so you can see exactly how a shortcode behaves before using it.

Shortcodes come from two places:

• docs/layouts/shortcodes/ — defined in this repository and documented in full below.
• The Docsy theme — inherited, and summarized under Inherited Shortcodes.

The Meshery documentation also imports github.com/layer5io/docs as a Hugo module, but that import is mounted to a single partial in hugo.toml and contributes no shortcodes.

Shortcode Delimiters

Hugo shortcodes are invoked with one of two delimiter pairs, and the choice changes how the shortcode's body is treated:

Shortcodes defined in this repository that take a body render it themselves via .Page.RenderString, and therefore expect the {{</* */>}} form. The inherited Docsy callouts expect {{%/* */%}}. Each entry states which form to use.

The form a shortcode expects is determined by its implementation, not by convention. When an entry here disagrees with what you see on the site, the file in docs/layouts/shortcodes/ is the source of truth, and the entry needs fixing.

Meshery Shortcodes

Listed alphabetically.

code

Wraps a snippet in a styled code block with a copy-to-clipboard button, without needing a manually assigned ID per snippet.

Use when the reader is expected to copy and run the snippet. For code that is only being read — illustrative output, config fragments under discussion — a standard fenced block is lighter and easier to maintain.

Takes no body. Use the {{</* */>}} form.

Syntax

{{</* code code="make site" */>}}

Rendered output

{{< code code="make site" >}}

{{% alert color="warning" title="Note" %}} Don't use the code shortcode when the snippet appears between items of an ordered list — it breaks the numbering, and the item following the snippet restarts at 1. {{% /alert %}}

discuss

Renders a static callout linking to the Meshery Discussion Forum.

Use when closing a page where readers are likely to have follow-up questions. The text is fixed, so one per page at most.

Takes no parameters and no body.

Syntax

{{</* discuss */>}}

Rendered output

{{< discuss >}}

extension-guide

Renders a responsive card grid from a data file in docs/data/. Each card shows an image, a title, and a description.

Use when presenting a set of parallel options the reader chooses between — component types, extension points — where a visual grid aids scanning. For a linear list of links, use section-pages.

Takes no body. Use the {{</* */>}} form.

Syntax

{{</* extension-guide
  data_file="edges"
  guide_title="Edge"
  guide_description="Description"
  guide_svg="SVG"
  guide_assests_folder="shapes"
*/>}}

Rendered output

{{< extension-guide data_file="edges" guide_title="Edge" guide_description="Description" guide_svg="SVG" guide_assests_folder="shapes"

}}

latest-release

Prints the tag of the most recent non-prerelease entry under the releases content type.

Use when a page needs to show the current release and would otherwise go stale. Note that it emits an <h2>, so the release tag appears in the page's table of contents.

Takes no parameters and no body.

Syntax

{{</* latest-release */>}}

Rendered output

{{< latest-release >}}

model-categories

Renders one <li> per model category, each with a parenthetical count of the models in that category, ordered by count descending.

Use when listing categories inside an existing list. This shortcode emits list items only — you must supply the surrounding <ul> or <ol> yourself, or the items will render unwrapped.

Counts are derived from the integrations-category param on each model page, so they stay accurate as models are added or recategorized. Category names are plain labels rather than links, because the models index is a single alphabetized page with no per-category filtering.

Takes no parameters and no body.

Syntax

<ul>
  {{</* model-categories */>}}
</ul>

Rendered output

model-count

Prints the current total number of Meshery models, counted from the pages under extensions/models/.

Use when a sentence quotes the model total and would otherwise need manual updating as models are added.

Takes no parameters and no body. Emits a bare number, so it composes inline.

Syntax

Meshery currently supports {{</* model-count */>}} models.

Rendered output

Meshery currently supports {{< model-count >}} models.

related-discussions

Lists up to eight forum topics matching a tag, plus a link to view all discussions with that tag.

Use when an active forum tag maps closely to the page topic. Topics are read from site.Data.discuss.<tag>, not fetched at request time — if no data file exists for the tag, only the "view all" link renders, with no error. Output changes as that data is refreshed, so don't write prose that depends on which topics appear.

Takes no body. Use the {{</* */>}} form.

Syntax

{{</* related-discussions tag="meshery" */>}}

Rendered output

{{< related-discussions tag="meshery" >}}

relationships

Inserts a predefined, collapsible set of visual examples of component relationships, grouped by kind and subtype, each linking to the design in the playground.

Use when explaining how components relate structurally. The content is fixed — it takes no parameters and cannot be scoped to a subset of relationship kinds.

Takes no parameters and no body.

Syntax

{{</* relationships */>}}

Rendered output

{{< relationships >}}

section-pages

Renders one <li> per immediate child page of a section, each linking to the page and appending its description from front matter when set.

Use when a landing page should index its children and stay correct as pages are added or removed. This shortcode emits list items only — you must supply the surrounding <ul> or <ol> yourself.

Pages are sorted by title. A page is excluded when its front matter sets hide_homepage, and the section's own landing page is always excluded. The final path segments quick-start and faq are excluded unconditionally by the implementation. When nothing matches, a single italic "No pages found in this section." item renders in place of the list.

Takes no body. Use the {{</* */>}} form.

Syntax

<ul>
  {{</* section-pages section="concepts/architecture" */>}}
</ul>

Rendered output

static

Resolves a path into a site-relative URL.

Use when referencing an asset from a page that may be moved, or where baseURL differs between local and production builds. Most commonly nested inside an `` tag or a Markdown image link.

Takes no body. Use the {{</* */>}} form.

Syntax

![Meshery Architecture]({{</* static "images/meshery-architecture.webp" */>}})

Rendered output

![Meshery Architecture]({{< static "images/meshery-architecture.webp" >}})

tabs

Organizes content into selectable tabs.

Use when presenting the same task across mutually exclusive contexts — operating systems, installation methods — where the reader needs exactly one branch. Don't use it for sequential content; readers miss what's behind an unselected tab.

Takes a body. Use the {{</* */>}} form. Within the body:

• Separate tabs with an <!-- tab --> HTML comment.
• The first line of each block is the tab label; the content begins after the first blank line.
• A label may carry an icon by appending | and an icon value. A value starting with fa is treated as a Font Awesome class; anything else is inserted as raw markup.
• The first non-empty block is selected by default.

Syntax

{{</* tabs id="example-tab-group" */>}}
Tab 1 Title

This is the content for the first tab.
<!-- tab -->
Tab 2 Title | fas fa-cog

This is the content for the second tab.
{{</* /tabs */>}}

Rendered output

{{< tabs id="example-tab-group" >}} Tab 1 Title

This is the content for the first tab.

Tab 2 Title | fas fa-cog

This is the content for the second tab. {{< /tabs >}}

Snippet shortcodes

Some shortcodes are Markdown files in subdirectories of docs/layouts/shortcodes/ rather than templates, and are invoked by path. They take no parameters and no body, and exist to keep a reusable block of prose in one place:

To add one, drop a .md file into the relevant subdirectory — no template is required.

Data-Driven Shortcodes

The shortcodes below each render a full, live dataset — error codes, vulnerabilities, mesheryctl commands, permissions, and so on — pulled from docs/data/ or the site's own content. Because their real output can run to hundreds of rows and changes as that underlying data changes, this section shows the invocation syntax and links to the page where each one is used, rather than re-rendering the full table here.

All of them take no body, and all take no parameters except mesheryctl-command-table, which requires a command naming the command whose subcommands are tabulated.

Inherited Shortcodes

These come from the Docsy theme rather than this repository. They are listed here because they appear throughout the Meshery documentation and contributors will encounter them; the Docsy shortcode reference is authoritative for their full behavior.

alert

Renders a coloured callout box with a heading.

Use when flagging a warning, prerequisite, or caveat that would interrupt the flow of the surrounding paragraph. For inline emphasis, use bold instead — a page dense with callouts trains readers to skip them.

Takes a body. Use the {{%/* */%}} form, or the body's Markdown will render as literal asterisks and backticks.

Syntax

{{%/* alert color="warning" title="Note" %}}
Run `make site` locally before opening your PR.
{{% /alert */%}}

Rendered output

{{% alert color="warning" title="Note" %}} Run make site locally before opening your PR. {{% /alert %}}

pageinfo

Renders a page-scoped information banner.

Use when the note applies to the whole page — deprecation, beta status, "applies to version X" — and belongs above the content. For a note scoped to one section, use alert.

Takes a body. Use the {{%/* */%}} form.

Syntax

{{%/* pageinfo color="info" %}}
This page describes a **beta** feature.
{{% /pageinfo */%}}

Rendered output

{{% pageinfo color="info" %}} This page describes a beta feature. {{% /pageinfo %}}

Docsy also provides youtube, imgproc, blocks/*, cardpane, and others. See the Docsy reference for those.

Adding a New Shortcode

Shortcode implementations live in docs/layouts/shortcodes/. The filename becomes the shortcode name: docs/layouts/shortcodes/model-count.html is invoked as {{</* model-count */>}}, and a file in a subdirectory is invoked by path, as {{</* mesheryctl/installation-bash */>}}.

A template in this repository overrides a theme template of the same name, so adding docs/layouts/shortcodes/alert.html would replace Docsy's alert site-wide. Do that deliberately, if at all.

1. Create the template. Open with a comment block stating what the shortcode outputs, any assumptions it makes about page location or front matter, and a usage line.

2. Guard your assumptions. Shortcodes are invoked from pages you did not write. Check that the values you depend on exist before indexing into them.

3. Choose a failure mode deliberately. Use errorf when a missing argument means the author made a mistake that must be fixed, as tabs does when id is absent. Use warnf, or emit nothing, when the page still renders usefully without the output. Both take .Position so the message names the file and line.

4. Control whitespace. Use {{- -}} trim markers so the shortcode does not emit stray newlines into the surrounding Markdown, which can break list numbering and inline usage.

5. Say what wrapping the caller must supply. A shortcode that emits bare <li> elements, as section-pages and model-categories do, is unusable without that fact being written down.

6. Document it here. Add an entry to the catalog above with the parts every entry carries: a description, a "use when" line, a parameter table, and a syntax and rendered-output pair. A shortcode that isn't on this page is a shortcode contributors won't find.

Example. model-count derives its number from the site's own content rather than a hardcoded value, so the figure never goes stale:

{{- $models := where site.RegularPages ".File.Dir" "like" `^extensions/models/` -}}
{{- len $models -}}

Note: When a shortcode can produce empty or zero output without failing, its entry above must say so, or contributors will read the result as a bug and file it as one.

{{% alert color="warning" title="Register your shortcode" %}} If a new shortcode ships without an entry on this page, contributors have no way to discover it short of reading docs/layouts/shortcodes/, which is the problem this page exists to solve. Treat the catalog entry as part of the shortcode, not as follow-up work. {{% /alert %}}