1. Docs
2. Live examples

The example shortcode

A folder next to your page, one line in its Markdown, and the example runs.

A first example#

Make the page a page bundle (a folder with an index.md) and put the example’s files in a folder next to it:

content/examples/counter/
├── index.md
└── demo/
    ├── example.html    required: the markup
    ├── style.css       optional
    └── script.js       optional

Then, in index.md:

{{< example "demo" >}}

This is the counter example, running (its files live in assets/examples/counter/, so this page and the Examples tab can share them; more below):

<button id="counter" type="button">Clicked <output>0</output> times</button>

/* A plain "button" selector: the theme wraps this file in @scope, so it reaches this example's button only */
button {
  padding: 0.6rem 1.2rem;
  border-radius: 999px;
  font-size: 1.1rem;
}

const button = document.getElementById("counter");
const output = button.querySelector("output");
let count = 0;

button.addEventListener("click", () => {
  count += 1;
  output.value = count;
});

The frame’s label says “live” and the example’s title. Under it, the files in tabs, with a copy button for the file shown.

Options#

Pass the folder’s name alone, as above, or as name with other options:

{{< example name="demo" title="Captions" >}}
{{< example name="demo" run="false" >}}
{{< example name="dialog" frame="false" >}}

A shortcode call takes either one name or named options, not both: {{< example "demo" title="x" >}} is an error.

Where the files can live#

The shortcode looks for <name>/example.html in two places, in this order:

1. next to the page, in its bundle: for examples that belong to one page;
2. in your site’s assets/examples/<name>/: for examples several pages share, or examples on pages that aren’t bundles (the start page’s random walk lives in assets/examples/walk/).

Shared parts#

Some examples need markup that isn’t part of what they demonstrate. The photo viewer needs one <dialog> per page. Put it in an example of its own and run it bare, with frame="false":

{{< example name="demo" title="Photo viewer" >}}

{{< example name="dialog" frame="false" >}}

The bare example’s markup, style and script go into the page without a frame or tabs. Write about it once, on a page of its own, and show its files there.

Paths in the markup#

Write paths in example.html the way they’d look on your own site, from its root:

<img src="/media/photo-1-480.jpg" alt="…">

If your docs live under a subpath, say example.org/docs/, Vitrine adds it to every src, href and poster starting with / when the example runs. The files in the tabs keep the path as you wrote it.

What else to know#

• Ids are page-wide. Every example’s markup is part of the page, so two examples on one page can’t use the same id. Give elements ids that name the example (counter, walk-again).
• Scripts run once, as modules, after the page is parsed. They see the whole page, so select your elements by id, not by tag.
• No <html> or <body> in example.html: it’s a fragment that goes into the page.