Tips & Tricks

Tips & Tricks

Escaping Characters

For Markdown syntax: To display a literal character that are normally used for Markdown formatting, add a backslash (\) in front of the character.

CODE:

\* item 1

* item 1

OUTPUT:

* item 1

  • item 1

More info: https://www.markdownguide.org/basic-syntax#escaping-characters

Using {% raw %}{% endraw %} to display {{ content }}

By default, MarkBind processes any code in the form of {{ content }}. This is because Nunjucks (which is supported by MarkBind) uses this syntax to evaluate an expression, variable, or function calls. For instance:

{{ username }}

This will not display {{ username }} as a raw string, but instead, look up the variable username from the context and display its value.

In general, to use this syntax as a raw string in a code block or a template, there are two methods available. The syntax can either be encased as a variable like {{ '{{' }} and {{ '}}' }}, or alternatively, the entire code block can be encased with the raw-endraw tags: {% raw %} {{ content }} {% endraw %}.

If using raw-endraw tags outside <code> elements, markdown code fences, or inline code, you also need to add the v-pre attribute.

For HTML elements, the v-pre attribute needs to be declared as part of the HTML tag:

{% raw %}

<div v-pre>
  <p>{{ content }}</p>
</div>

{% endraw %}

For Markdown elements, the v-pre attribute needs to be declared using markdown-it-attrs, which allows classes, identifiers, and attributed to be added to Markdown syntax:

{% raw %}

# Header with {{ content }} {v-pre}

{% endraw %}

Otherwise, any HTML or Markdown content containing double curly braces will be processed as a variable and will not be displayed properly.

Note: This step isn't necessary for <code> elements, markdown code fences and inline code because MarkBind automatically adds v-pre for them.

When you use links or triggers, you may encounter a situation where an unwanted space is being generated by MarkBind:

  • Code:

    The
[[link](https://example.com)].

  • Expected output: The [link].

  • Actual output (notice the additional space in front of the link): The [ link].

  • Solution: Wrap the link or trigger around with <md> tags.

    The
<md>[[link](https://example.com)]</md>.
Configuring Online Deployment platforms to use specific MarkBind version

Configuring CI platforms to use specific MarkBind version

When the default CI configuration for deployment is used, the latest version of MarkBind will be used in the CI workflows. This may be a later version of MarkBind than the one you use locally.

  • If you want to specify a version of MarkBind (eg. v1.6.3), you have to modify the step where markbind-cli is being installed to npm i -g markbind-cli@v1.6.3. For example, for Travis-CI, you can modify the install step in .travis.yml as follows:

    install:
  - npm i -g markbind-cli@1.6.3

  • If you want to use the latest minor version automatically until the next major version (as major versions usually contain breaking changes), you can add a ^ in front of the version number. In the example below, Travis will use the latest version of MarkBind but will stop before 2.*

    install:
  - npm i -g markbind-cli@^1.6.3

Setting up Netlify to use a specific version of MarkBind

Here are the steps to set up Netlify to use a specific version of MarkBind.

  1. Navigate to the root directory of your site.

  2. Run npm init which will create package.json and package.lock.json

  3. Run npm install markbind-cli@1.6.3 --save to install MarkBind as a dependency (using v1.6.3 as an example)

  4. Create / Update .gitignore file in the root directory and add:

    node_modules

  5. Update ignore in site.json to include

    node_modules/*
.gitignore

  6. Now, follow the previous instructions for setting up Netlify but with the following difference:
    In step 5, Set the Build Command to markbind build --baseUrl

Indent components

In some cases, you may want to indent components such as panels and boxes to match the surrounding content. This is easily achieved by adding some margin and padding utility classes from Bootstrap to the component. The following examples show how to do this.

Indent Box component

CODE:

<box>Some text at level 1</box>

<box class="ms-4">Some text at level 2</box>

<box>Some text at level 1</box>

OUTPUT:

Some text at level 1
Some text at level 2
Some text at level 1

Indent Panel component

CODE:

<panel header="This panel is at level 1">
  ...
</panel>
<panel header="This panel is at level 2" class="ms-3">
  The "ms-3" is arbitarily chosen i.e "ms-0" to "ms-5" are all possible values.
</panel>
<panel header="This panel is at level 1">
  ...
</panel>

OUTPUT:

This panel is at level 1

This panel is at level 2

This panel is at level 1

Indent Included component

The following box component will be included via <include>.

Some text from include

CODE:

<box>Some text at level 1 (before included content)</box>
<include src="tipsAndTricks.md#forIndentDemo" class="ms-5"></include>
<box>Some text at level 1 (after included content)</box>

OUTPUT:

Some text at level 1 (before included content)
Some text from include
Some text at level 1 (after included content)