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:
😃
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 blockc1
,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 usingc1
) - Second case:
:::alert{...}
(2 + 1 = 3 colons usingc1
)
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"}
:::
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:

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