This site documents developmental features of CustardUI (head of develop branch) and possible breaking changes. For the latest stable release, visit here.

Getting Started

Getting Started

Thanks for taking the time to set up CustardUI on your site. This guide covers everything you need to go from a blank config to a fully personalized, reader-adaptive site.

CustardUI is designed to stay out of your way — you write your content as normal, and wrap or annotate the parts that should adapt. No build steps, no backend, no framework lock-in.

What's in this guide

  • Getting Started — install the script, create your config, and add your first component
  • Configuration — full reference for config.json, including toggles, tab groups, placeholders, and adaptations
  • Components — detailed docs for each component:
    • Toggles — show, hide, or peek content sections
    • Tabs — synced tab groups that remember the reader's choice
    • Placeholders — reader-defined values substituted into your content
    • Settings Panel — the built-in UI your readers use to manage their preferences
    • Focus & Share — shareable deep links that highlight any element on the page
  • URL Sharing — how the highlight parameter works and how to construct share links
  • Adaptations — serve different audiences from a single deployment
  • Integrations:

If something isn't working as expected or you want to request a feature, open an issue on GitHub.

Prerequisites

  • A basic understanding of HTML syntax
  • A static site to add CustardUI to (plain HTML, Jekyll, Hugo, MarkBind, etc.)

Quick Start

1. Add the Script Tag

Add the following to your HTML <head> or before the closing </body> tag:

<script src="https://unpkg.com/@custardui/custardui" data-base-url="/"></script>

Set data-base-url to your site's base path. For example, if your site is hosted at /docs, use data-base-url="/docs".

2. Create a Config File

Create a custardui.config.json file at your site root. This tells CustardUI what toggles and options to expose:

{
  "config": {
    "toggles": [
      { "toggleId": "mac", "label": "macOS", "description": "Show macOS instructions" },
      { "toggleId": "win", "label": "Windows", "description": "Show Windows instructions" }
    ]
  },
  "settings": {
    "enabled": true
  }
}

3. Use Features and Components in Your Content

Try using CustardUI's features and components in your content.

Try typing #cv-share in your url bar to bring up the share toolbar, and try generating a shareable link of your page.

Additionally, try using <cv-toggle> elements around any content you want to conditionally show or hide:

<cv-toggle toggle-id="mac">
  This content is only shown to macOS users.
</cv-toggle>

<cv-toggle toggle-id="win">
  This content is only shown to Windows users.
</cv-toggle>

That's it. Open your page and you'll see a settings icon on the left — click it to switch between views. Selections are saved automatically.

What's Next?

Now that CustardUI is running, explore its features:

Using MarkBind? See the MarkBind integration guide for a plugin-based setup.

Troubleshooting

Settings icon not appearing?

  • Make sure "settings": { "enabled": true } is present in your config file.
  • Check your browser console for errors.
  • Ensure custardui.config.json is accessible via the Network tab in DevTools.