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

	

		make site
	

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

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

Arrow Head

Represents general direction or flow in diagrams. In UML, it could indicate direction in an association or dependency.

Bezier Curve Line

Used for curved relationships, which might indicate non-linear or non-direct connections. In UML, it could be used for inheritance or flow that isn't straightforward.

Filled Circle Head

Used for aggregation in UML, where one class contains another but does not own it (e.g., a library containing books).

Filled Diamond Head

Used for aggregation in UML, typically an empty diamond at the container end, indicating a "whole-part" relationship.

Filled Square Head

Represents composition in UML, a stronger relationship than aggregation, where the contained class cannot exist without the container (e.g., a house and its rooms).

Filled Triangle Head

Often used for inheritance in UML, where one class is a subclass of another. It indicates the "is-a" relationship.

Line With Circles

Often represents a weak or indirect association in UML. It can also be used for dependencies or indicating optional relationships.

Smooth Line With Circle

Represents a smooth transition or flow between elements. It could be used in scenarios where gradual change or influence is depicted.

Straight Line

Represents a simple association or direct relationship between two entities or classes in UML.

Tree Line

Represents hierarchical relationships, such as a parent class with child classes, or a main system branching into subsystems.

Wave Line

Typically used to represent asynchronous signals or connections that aren't continuous. It may also denote complex relationships or uncertain flows in certain custom diagrams.

Zigzag Line

This is often used to represent signals with interference or noise. In system design, it can be used to indicate a disrupted or unreliable connection.

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

v1.0.64

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

• App Definition and Development (84)
• Provisioning (69)
• Observability and Analysis (56)
• Cloud Native Network (43)
• Orchestration & Management (35)
• Security & Compliance (30)
• Database (19)
• Runtime (18)
• Cloud Native Storage (10)
• Tools (8)
• Serverless (7)
• Machine Learning (6)
• Platform (6)
• Analytics (2)

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 393 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

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

Example Visual Representations

Kind: Hierarchical

Kind: Edge

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

• Adapters - Adapters extend Meshery's management capabilities in any number of ways, including lifecycle, configuration, performance, governance, identity...
• Broker - Meshery broker component facilitates data streaming between kubernetes cluster components and outside world.
• Catalog - Browsing and using cloud native patterns
• Database - Meshery offers support for internal caching with the help of file databases. This has been implemented with several libraries that supports different kinds of data formats.
• MeshSync - MeshSync ensures Meshery Server is continuously in-sync with the state of infrastructure under management.
• Operator - Meshery Operator controls and manages the lifecycle of components deployed inside a kubernetes cluster

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 <img> tag or a Markdown image link.

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

Syntax

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

Rendered output

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

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

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

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.