MarkBind - User Guide: Using Plugins

Using Plugins

A plugin is an extension that adds additional features to MarkBind. Some non-essential MarkBind functionalities are provided as plugins so that you can enable/disable/configure them as necessary. MarkBind also supports adding external plugins (written by you or other third parties).

MarkBind's philosophy is to bake-in all necessary functionality into MarkBind itself rather than expect users to go hunting for suitable plugins. Hence, we do not anticipate MarkBind users to rely heavily on such external plugins.

Managing Plugins

Plugins are managed via the following two properties in the site.json.

plugins: An array of plugin names to use.
pluginsContext: Parameters passed to each plugin, specified as key-value pairs.

For example:

{
  ...
  "plugins": [
    "plugin1",
    "plugin2",
  ],
  "pluginsContext": {
    "plugin1": {
      "input": "Input for Plugin 1"
    },
    "plugin2": {
      "data": "Data for Plugin 2"
    }
  }
}

Using Built-in Plugins

MarkBind has a set of built-in plugins that can be used immediately without installation.

Plugin: Algolia

This plugin allows you to use Algolia DocSearch for your site.

To enable it, add algolia to your site's plugins, and supply the required options via the pluginsContext.

Name	Type	Default	Description
apiKey	`String`		The API key for your site's Algolia DocSearch setup
appId	`String`		The application id for your site's Algolia DocSearch setup
indexName	`String`		The index name for your site's Algolia DocSearch setup
searchParameters	`Object`	`{}`	A JSON object specifying the Algolia Search Parameters

site.json
{
  ...
  "plugins": [
    "algolia"
  ],
  "pluginsContext": {
    "algolia": {
      "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // replace with your site's api key
      "appId": "R2IYF7ETH7", // replace with your site's application id
      "indexName": "docsearch", // replace with your site's index name
      "searchParameters": { "facetFilters": ["site:yoursite.com"] } // optional
    }
  }
}

To connect the searchbar component to Algolia DocSearch, add the algolia key.

<searchbar placeholder="Search" algolia menu-align-right></searchbar>

Alternatively, if you are using a custom search bar, you can assign the div element the id algolia-search-input to connect it to Algolia DocSearch.

<div id="algolia-search-input"></div>

By default, Algolia DocSearch indexes all content on the page, including content in components that are hidden to the user during the initial render (e.g. Panels). To exclude these content from being indexed, you can add .algolia-no-index to the selectors_exclude attribute in your DocSearch configuration.

The algolia-no-index class is automatically added to content hidden by MarkBind's Vue components. You may also add the algolia-no-index class to content that you do not want to be indexed by Algolia DocSearch.

Plugin: `codeBlockCopyButtons`

This plugin adds a copy button to fenced code blocks so that readers can copy the code easily.

To enable it, simply add codeBlockCopyButtons to your site's plugins.

site.json

{
  ...
  "plugins": [
    "codeBlockCopyButtons"
  ],
}

This is what it'll look like once added:

Plugin: `codeBlockWrapButtons`

This plugin adds a wrap text button to fenced code blocks so that readers can read long lines of code without scrolling sideways.

To enable it, simply add codeBlockWrapButtons to your site's plugins.

site.json

{
  ...
  "plugins": [
    "codeBlockWrapButtons"
  ],
}

This is what it'll look like once added:

Clicking the wrap text button will result in the following:

In case a single long word is encountered, it will be split across multiple lines similar to the following:

Plugin: Tags

With this plugin you can use tags to selectively filter content when building a site.

Toggling alternative contents

Tags are specified by the tags attribute, and can be attached to any HTML element. During rendering, only elements that match tags specified in the site.json files will be rendered.

Example Attaching tags to elements:

# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>

You need to specify the tags to include in the pluginsContext, under tags:

{
  ...
  "plugins" : [
    "filterTags"
  ],
  "pluginsContext" : {
    "filterTags" : {
      "tags": ["language--java"]
    }
  }
}

All other tagged elements will be filtered out. In this case, only the element with the language--java tag will be rendered. This is helpful when creating multiple versions of a page without having to maintain separate copies.

If the filterTags plugin is not enabled in site.json, all tagged elements will be rendered.

You can also use multiple tags in a single HTML element. Specify each tag in the tags attribute separated by a space. An element will be rendered if any of the tags matches the one in site.json.

Example Attaching multiple tags to an element:

# For loops

<p tags="language--java language--C#">for (int i = 0; i < 5; i++) { ... }</p>

As long as the language--java or language--C# tag is specified, the code snippet will be rendered.

Alternatively, you can specify tags to render for a page in the frontmatter.

Example Specifying tags in frontmatter:

<frontmatter>
  title: "Hello World"
  tags: ["language--java"]
</frontmatter>

<p tags="language--java advanced">System.out.println("Hello world");</p>
<p tags="language--C# basic">Console.WriteLine("Hello world");</p>

<frontmatter>
  title: "Hello World"
  tags: ["language--java"]
</frontmatter>

Tags in site.json will be merged with the ones in the frontmatter, and are processed after frontmatter tags. See Hiding Tags for more information.

Advanced Tagging Tips

You can use a * in a tag name to match elements more generally. A * in a tag will match any number of characters at its position.

Example Using general tags:

<frontmatter>
  title: "Hello World"
  tags: ["language--*"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>

All 3 <p>s will be shown.

Hiding Tags

Using - at the start of a tag hides all tags matching the expression. This is helpful for disabling a group of tags and enabling a particular tag.

Example Using general tags:

index.md
<frontmatter>
  title: "Hello World"
  tags: ["language--java"]
</frontmatter>

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>

site.json
{
  ...
  "plugins" : [
    "filterTags"
  ],
  "pluginsContext" : {
    "filterTags" : {
      "tags": ["-language--*", "language--C#"]
    }
  }
}

language--java is overridden by -language--*, so only language--C# is shown.

This only works because tags are processed left to right, so all language--* tags are hidden before language--C#. Tags in site.json are processed after tags in <frontmatter>.

# Print 'Hello world'

<p tags="language--java">System.out.println("Hello world");</p>
<p tags="language--C#">Console.WriteLine("Hello world");</p>
<p tags="language--python">print("Hello world")</p>

{
  ...
  "plugins" : [
    "filterTags"
  ],
  "pluginsContext" : {
    "filterTags" : {
      "tags": ["language--java"]
    }
  }
}

Plugin: GoogleAnalytics

This plugin allows your web pages to be captured by google analytics.

To enable it, add googleAnalytics to your site's plugins, and add the trackingID parameter via the pluginsContext.

Name	Type	Default	Description
trackingID	`String`		Tracking ID provided by Google. Follow this guide to get your Tracking ID.

site.json
{
  ...
  "plugins": [
    "googleAnalytics"
  ],
  "pluginsContext": {
    "googleAnalytics": {
      "trackingID": "YOUR-TRACKING-ID", // replace with your google analytics tracking id.
    }
  }
}

Plugin: Disqus

This plugin allows you to use Disqus for your site.

Before you can use this plugin, you need to (1) setup a Disqus account and (2) register your site.

You may sign up for a Disqus account and register your site here.

Note that you do not have to install Disqus on your site, this plugin does it for you.

All you have to do is provide the shortname of your Disqus site, which is explained below.

To enable this plugin, add disqus to your site's plugins, and supply the required options via the pluginsContext.

Name	Type	Default	Description
shortname	`String`		Shortname is provided by Disqus. Follow this guide to get shortname for your Disqus site.

site.json
{
  ...
  "plugins": [
    "disqus"
  ],
  "pluginsContext": {
    "disqus": {
      "shortname": "YOUR_DISQUS_SITE_SHORTNAME", // replace with your Disqus site's shortname 
    }
  }
}

Then, to add a Disqus comment section on a page, all you need to do is to add a <disqus/> HTML tag to any MarkBind source file.

It may be a good idea to create a layout with <disqus/> in it, so that you won't have to repeat it on every page.

Plugin: MathDelimiters

This plugin allows you to use additional delimiters for your math formulae. Available delimiters are listed in the markdown-it-texmath package.

These delimiters are supported without guarantee that they will be rendered correctly, especially when they happen to conflict with other MarkBind syntax.

Note that the default delimiters still function as expected, this plugin simply adds the additional delimiters.

To enable this plugin, add mathDelimiters to your site's plugins and specify the delimters in the context.

site.json
{
  ...
  "plugins": [
    "mathDelimiters"
  ],
  "pluginsContext" : {
    "mathDelimiters" : {
      "delimiters": ["beg_end"]
    }
  },
}

Example with beg_end delimiters:

CODE:

\begin{equation}
  a^2+b^2=c^2
\end{equation}

\begin{equation}
  \begin{pmatrix}
    A & B \\ B & C
  \end{pmatrix}
\end{equation}

OUTPUT:

\begin{equation} a^2+b^2=c^2 \end{equation}

\begin{equation} \begin{pmatrix} A & B \\ B & C \end{pmatrix} \end{equation}

Plugin: Web3Forms

This plugin allows you to create forms whose response will be sent directly to your email, using the Web3Forms API.

Don't forget to check your spam/junk folder if your form responses aren't appearing in your inbox!

The free plan from Web3Forms allows up to 250 submissions per month.

To set it up, get an access key from Web3Forms. Then add web3Form to your site's plugin, and add the accessKey parameter via the pluginsContext.

Name	Type	Default	Description
accessKey	`String`		accessKey is required. It is provided by Web3Forms.

site.json
{
  ...
  "plugins": [
    "web3Form"
  ],
  "pluginsContext": {
    "web3Form": {
      "accessKey": "YOUR_WEB_3_FORM_ACCESS_KEY" // replace with your Web3Forms access key 
    }
  }
}

The access key is exposed to public. This is generally ok since the access key is an alias to your email and is equivalent to revealing your email to public.

However it is possible that malicious users might use the access key in other forms. This might subject the email linked to the access key to spam with irrelevant form submissions.

To add a form to your site, use a <web-3-form> tag.

CODE:

<web-3-form header="Contact Us">
    <label for="name">Name</label>
    <input type="text" name="name" required placeholder="John Doe">
    <button type="submit">Submit</button>
</web-3-form>

OUTPUT:

Name

Web3Forms plugin also supports a default 'Contact Us' form.

The header will be <p class="h2">Contact Us</p> for the default form if no header is specified. This uses Bootstrap to style the header.

CODE:

<web-3-form default />

OUTPUT:

CODE:

<web-3-form default header="**New header**"/>

OUTPUT:

Web3Forms plugin supports common inputs.

The inputs supported are

name-input
email-input
message-input
submit-button

CODE:

<web-3-form header="**Form with name input**">
<name-input></name-input>
</web-3-form>

<web-3-form header="**Form with email input**">
<email-input></email-input>
</web-3-form>

<web-3-form header="**Form with message input**">
<message-input></message-input>
</web-3-form>

<web-3-form header="**Form with submit button**">
<submit-button></submit-button>
</web-3-form>

OUTPUT:

Web3Forms plugin supports customised header and styles

Options from the box component are supported here.

CODE:

<web-3-form default type="warning" header="Here's a form :rocket:" color="red" dismissible>
</web-3-form>

OUTPUT:

Using External Plugins

Adding External Plugins

WARNING: Plugins are executable programs that can be written by anyone. This means that they might contain malicious code that may damage your computer.

Only run plugins from sources that you trust. Do not run the plugin if the source/origin of the plugin cannot be ascertained.

Plugins come as .js files. To install an external plugin, simply put it in the _markbind/plugins folder. To use the plugin, update the site.json file the same way you did for built-in plugins.

Writing Plugins

You may also write your own plugins! Refer here for the available interfaces to do so.

Setting Site Properties

Making the Site Searchable

Using Plugins

Managing Plugins

Using Built-in Plugins

Plugin: Algolia

Plugin: codeBlockCopyButtons

Plugin: codeBlockWrapButtons

Plugin: Tags

Toggling alternative contents

Advanced Tagging Tips

Hiding Tags

Plugin: GoogleAnalytics

Plugin: Disqus

Plugin: MathDelimiters

Plugin: Web3Forms

Using External Plugins

Adding External Plugins

Writing Plugins

Plugin: `codeBlockCopyButtons`

Plugin: `codeBlockWrapButtons`