Snippets
Write a block once, include it in many pages.
Snippets
Section titled “Snippets”A snippet is a shared block of content. Edit it once and every page that includes it changes.
Writing one
Section titled “Writing one”Create a file under snippets/. The file name without its extension is the
name.
:::hint{type="tip"}Stuck? Ask in the shared channel, or open an issue on the repository.:::Including one
Section titled “Including one”::snippet{name="support-callout"}A snippet name that has no file fails the undefined-snippet rule, so a commit
cannot leave a page including something that is not there.
What a snippet is for
Section titled “What a snippet is for”Good uses:
- a support callout that appears on twenty pages;
- a prerequisites block shared by every guide in a section;
- a deprecation notice you will remove from everywhere at once.
Poor uses:
- one paragraph used twice. The indirection costs the reader more than the duplication costs you.
- a whole page. Make it a page and link to it.
Deleting one
Section titled “Deleting one”Before a snippet is deleted, the writer shows every page that includes it, and offers three choices: cancel, replace it with another snippet, or detach it into ordinary content at each use.
Detaching writes the snippet’s current content into each page. The pages keep saying what they said, and they stop being linked.
Snippets and variables
Section titled “Snippets and variables”A snippet is a block. A variable is a word. Use a variable for a product name or a URL, and a snippet for a paragraph or a callout.
A snippet may contain variables. They are resolved when the page is built, so
{{api_url}} inside a snippet resolves the same way it does on a page.