Setting up CustardUI in a MarkBind Site

CustardUI integrates seamlessly with MarkBind via a simple plugin setup. This allows you to declaratively toggle content visibility, manage tab groups, and personalize documentation directly within your static site.

Create the Plugin File

In your MarkBind project root, create a new folder named /_markbind/plugins/ if it doesn’t already exist.
Then, add a file named custardui.js inside it with the following content:

/**
 * CustardUI Plugin for MarkBind
 * Injects the CustardUI auto-init script into every page.
 * Configuration is loaded from websiteUrl/BaseUrl/custardui.config.json
 */
function getScripts() {
  return ['<script src="https://unpkg.com/@custardui/custardui" data-base-url="/"></script>'];
}

const tagConfig = {
  'cv-toggle': { isCustomElement: true },
  'cv-tabgroup': { isCustomElement: true },
  'cv-tab': { isCustomElement: true },
  'cv-tab-body': { isCustomElement: true },
  'cv-tab-header': { isCustomElement: true },
  'cv-define-placeholder': { isCustomElement: true },
  'cv-placeholder-input': { isCustomElement: true }
};

module.exports = { getScripts, tagConfig };

Note: Depending on your MarkBind JS environment, if you are operating in an ESM environment (e.g. there is a parent ESM package.json file), the plugin needs to be written in ESM format. If that is the case, try this the ESM format instead:

function getScripts() {
  return ['<script src="https://unpkg.com/@custardui/custardui" data-base-url="/"></script>'];
}

const tagConfig = {
  'cv-toggle': { isCustomElement: true },
  'cv-tabgroup': { isCustomElement: true },
  'cv-tab': { isCustomElement: true },
  'cv-tab-body': { isCustomElement: true },
  'cv-tab-header': { isCustomElement: true },
  'cv-define-placeholder': { isCustomElement: true },
  'cv-placeholder-input': { isCustomElement: true }
};

export { getScripts, tagConfig };

This is a current limitation of MarkBind which only operates in CJS formats, which may cause compatibility issues when operating in cross CJS and ESM environments.

This plugin automatically injects the CustardUI runtime into every generated page during the build process.

2. Register the Plugin in site.json

In your project’s root site.json, register the plugin by adding "custardui" to the plugins list.

{
  "plugins": ["custardui"]
}

Make sure the file name (custardui.js) exactly matches the plugin name (custardui) declared in site.json.

3. Create custardui.config.json

At your project root, create a custardui.config.json file to define your toggles, tab groups, and widget options.

{
  "config": {
    "toggles": [
      {
        "toggleId": "mac",
        "label": "MacOS",
        "description": "Show content for macOS users",
        "default": "peek"
      },
      { "toggleId": "linux", "label": "Linux", "description": "Show content for Linux users" },
      { "toggleId": "windows", "label": "Windows", "default": "show" }
    ],
    "tabGroups": [
      {
        "groupId": "fruit",
        "label": "Fruit Selection",
        "description": "Select your favorite fruit.",
        "isLocal": false,
        "default": "pear",
        "placeholderId": "fruit",
        "tabs": [
          { "tabId": "apple", "label": "Apple", "placeholderValue": "apple" },
          { "tabId": "orange", "label": "Orange", "placeholderValue": "orange" },
          { "tabId": "pear", "label": "Pear", "placeholderValue": "pear" }
        ]
      }
    ],
    "placeholders": [
      {
        "name": "username",
        "settingsLabel": "Your Username",
        "settingsHint": "Enter username",
        "defaultValue": "Guest"
      }
    ]
  },
  "baseUrl": "/",
  "storageKey": "unique-string",
  "settings": {
    "enabled": true,
    "panel": {
      "title": "CustardUI Settings Dialog",
      "description": "Toggle different content sections to customize your view."
    },
    "callout": {
      "show": true,
      "enablePulse": true,
      "message": "Open the CustardUI settings to customize your view.",
      "backgroundColor": "#198755",
      "textColor": "#ffffff"
    },
    "icon": {
      "position": "middle-left",
      "color": "#ffffff",
      "backgroundColor": "#198755",
      "opacity": 0.9,
      "scale": 1.1
    }
  }
}

After saving, run your MarkBind site locally:

markbind serve

If everything is configured correctly, you should see the settings widget floating on your site. Try toggling between views or switching tabs to confirm your setup is working. CustardUI will automatically handle visibility, persistence, and synchronization across all tabs and toggles.