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.