• HOME
  • USER GUIDE
  • SHOWCASE
  • ABOUT
  • 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
    indexName String The index name for your site's Algolia DocSearch setup
    algoliaOptions Object {} A JSON object specifying additional options for DocSearch
    debug Boolean false Whether to turn on debug mode to allow inspection of CSS styles for the dropdown
    site.json
    {
      ...
      "plugins": [
        "algolia"
      ],
      "pluginsContext": {
        "algolia": {
          "apiKey": "25626fae796133dc1e734c6bcaaeac3c", // replace with your site's api key
          "indexName": "docsearch", // replace with your site's index name
          "algoliaOptions": { "hitsPerPage": 10 }, // optional
          "debug": false // 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 input field the id algolia-search-input to connect it to Algolia DocSearch.

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

    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: 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 front matter.

    Example Specifying tags in front matter:

    <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 front matter, and are processed after front matter 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:

    <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>.

    ```html # Print 'Hello world'

    System.out.println("Hello world");

    Console.WriteLine("Hello world");

    print("Hello world")

    ``` ```json { ... "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.
        }
      }
    }
    

    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.