Snippets🔖

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

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 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"}
 
:::

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.

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