Hyperbook Documentation

Snippets

Sometimes you want to repeat a certain element, or you want to create your own element. Snippets allow you to do exactly that.

Snippet files need to be placed in the snippets folder at the root of your hyperbook beside the glossary and book folders.

Here we use a capital S for snippet. You need to use a small s.

You can access your hyperbook config in your snippets like so: {{{ hyperbook.name }}}.

Examples

Example 1: Block

Here is a simple example of a snippet for using a protect element with the same password and id across your hyperbook. The snippet located in snippets/password.md.hbs:

:::protect{id="1" password="hyperbook" description="The password is the name of this project."}
{{{ content }}}
:::
{{#if hint}}
:::alert{info}
Hyperbook is the password.
:::
{{/if}}

The markdown you need to place in your hyperbook:

:::Snippet{#password}
:smiley:
:::

The result:

The password is the name of this project.🔒

Example 2: Dynamic Colon Levels

Snippets automatically provide variables for different colon levels to handle proper nesting:

The snippet located in snippets/alert.md.hbs:

{{{ c1 }}}alert{label="Info" color="#3B82F6"}
{{{ content }}}
{{{ c1 }}}

Available colon level variables:

  • c - Same number of colons as the snippet block
  • c1, c2, c3, c4 - One to four more colons (for deeper nesting)
  • l1, l2, l3, l4 - One to four fewer colons (for shallower nesting)

Example usage with different nesting levels:

::::Snippet{#alert}
This will be wrapped in a 5-colon alert block.
::::
 
::Snippet{#alert}
This will be wrapped in a 3-colon alert block.
::

Results in:

  • First case: :::::alert{...} (4 + 1 = 5 colons using c1)
  • Second case: :::alert{...} (2 + 1 = 3 colons using c1)

This ensures proper nesting regardless of how deeply your snippet is nested within other markdown blocks.

Example 3: Block with Parameter

You can also pass parameters to your snippet to make them dynamic. For example our password snippet from above allows to pass a hint parameter. If the hint parameter is true, a alert element will be shown.

:::Snippet{#password hint=true}
 
::qr{value="https://hyperbook.openpatch.org" size="XL"}
 
:::
The password is the name of this project.🔒

Hyperbook is the password.

Example 4: Inline

{{#times n}}
  :smiley:
{{/times}}
:Snippet{#smiley n=10}

We are ten smilies: 😃 😃 😃 😃 😃 😃 😃 😃 😃 😃

Parameters

You can use the parameters by using curly brackets and the name of the parameter.

{{{p1}}}

Three curly brackets will give you the raw content.

Two curly brackets will give the HTML-escaped content.

Content

If your snippet spans across multiple lines, you can use the content parameter to use those. See Example 1.

You need to use three curly brackets for the content parameter.

Helpers

You can use the following helpers in your snippets

if

You can use the if helper to conditionally render a block.

{{#if p}}
  content
{{/if}}

unless

You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns a falsy value.

{{#unless hint}}
  content
{{/unless}}

times

You can use the times helper to repeat block.

{{#times 10}}
  Hi
{{/times}}

file

You can use the file helper to include the content of a file.

{{{file "/archives/project-1/main.c"}}}

You can also only use a few lines of the file.

{{{file "/archives/project-1/main.c" "1,3-4"}}}

And you can define an ellipsis.

{{{file "/archives/project-1/main.c" "1,3-4" "// ..."}}}

rfile

rfile work like file, but will read from root of a git repository. This is useful, when your hyperbook is in a subdirectory and you want to reference files from the root of the repository.

{{{rfile "/path/to/file"}}}

base64

You can use the bae64 helper to embedded media, even from external folders.

{{base64 "path/relative/to/root/folder"}}

This works best in conjunction with the image block:

![]({{base64 "path/relative/to/root/folder"}})

concat

{{concat "Hi" " there"}}

Hi there

camelcase

{{camcelcase "This is a test"}}

thisIsATest

pascalcase

{{pascalcase "This is a test"}}

ThisIsATest

dashcase

{{dashcase "This is a test"}}

This-is-a-test

lowercase

{{lowercase "This is a test"}}

this is a test

uppercase

{{lowercase "This is a test"}}

THIS IS A TEST

replace

{{replace "Give me Banana Banana" "Banana" "Apple"}}

Give me Apple Banana

replaceAll

{{replaceAll "Give me Banana Banana" "Banana" "Apple"}}

Give me Apple Apple

Snippets
✎ GitHub© Copyright 2025 by OpenPatch