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

✦ Open Source · Lightweight · Framework-Agnostic

CustardUI

Your docs, shaped for every reader. Memory-persistent interactivity for static sites — no backend required.

CustardUI adds tabs that sync across pages, content that hides until needed, and shareable deep links — all from a single script tag. Built for educational sites, documentation portals, and course textbooks.

Read the Docs View on GitHub

See it in action

Static sites don't have to be static.

The demo below is a live CustardUI-powered page. Try interacting with the tabs, toggles, and placeholders to see how they work.

Live Demo — Project Setup Guide

Hey, [[username]]! Let's get your project set up. Your name is remembered across every page on this site — set it once, see it everywhere.

Prerequisites

Make sure these are installed before continuing.

brew install node git

winget install OpenJS.NodeJS Git.Git

sudo apt install nodejs git

↑ peeked by default — visible enough to know it's there, collapsed until you actually need it

Installation

npm install custardui

yarn add custardui

pnpm add custardui

Configuration

Config file location varies by OS:

~/.config/custardui/config.json

%APPDATA%\custardui\config.json

~/.config/custardui/config.json

↑ synced with Prerequisites — switching OS above updates this automatically. No extra clicks.

Set "theme": "auto" to follow the reader's system preference. This is the most commonly missed config option. Share this step

Running the Project

npm run dev

yarn dev

pnpm dev

↑ synced with Installation — pick your package manager once, every code block on the site follows

Troubleshooting

Port already in use? Kill the process on port 3000:

lsof -ti:3000 | xargs kill

netstat -ano | findstr :3000
taskkill /PID <PID> /F

fuser -k 3000/tcp

↑ peeked by default — troubleshooting is there when you need it, invisible when you don't

Focus & Share

Answer questions with a link.

Did you notice the Share this step link in the demo above? Any element on the page can become a shareable, highlighted anchor — with or without an existing id. No more "scroll down and find the paragraph about the config file." You can even share this paragraph right here.

For TAs and instructors: When a student asks a question that's already answered on the site, share a URL like:

https://your-course-site.com/textbook?cv-highlight=the-element-id

The page loads with that section visually highlighted — drawing the student's eye straight to the answer.

Adaptations

One resource. Every audience.

Adaptations go beyond themes. They let different organizations share the same underlying content while each seeing a version tailored to them — logos, links, terminology, and all. No backend. No duplicate repositories.

Consider a Git mastery guide used by multiple courses:

Organization A — NUS CS2103T

Students see the CS2103T branding, TEAMMATES-specific Git workflow diagrams, and links to their course forum. The "fork and PR" model matches their exact project setup.

Organization B — A different course

The same guide, but with their own branding, a different recommended branching model, and links to their issue tracker. No content was duplicated — only the adaptation config differs.

This is how git-mastery.org uses CustardUI — a single site serving multiple audiences with zero backend infrastructure.

Getting started

Up and running in minutes.

No build step, no server to manage. Works with MarkBind, Jekyll, plain HTML — anything.

Add the script tag

Include the CustardUI CDN script in your base layout or page template.

Create your config

Add a config.json to your site root defining your toggles, tabs, and placeholders.

Use the components

Wrap content with <cv-toggle>, <cv-tabgroup>, and add [[placeholders]] anywhere.

<!-- Step 1: Add to your <head> or base layout -->
<script src="https://cdn.jsdelivr.net/npm/@custardui/custardui" data-base-url="/"></script>

// Step 2: config.json — define your toggles and tabs
{
  "config": {
    "toggles": [
      {
        "toggleId": "prerequisites",
        "label": "Prerequisites",
        "isLocal": true,
        "default": "peek"
      },
      ...
    ],
    "tabgroups": [
      {
        "groupId": "os",
        "tabs": [
          { "tabId": "macos", "label": "macOS" },
          { "tabId": "windows", "label": "Windows" },
          { "tabId": "linux", "label": "Linux" }
        ],
        ...
      }
    ],
    "placeholders": [
      {
        "name": "username",
        "defaultValue": "there",
        ...
      }
    ]
  },
  ...
}

Full documentation →

Your docs, shaped for every reader.

CustardUI is open source, free to use, and designed to slot into your existing workflow with minimal effort.

Get Started GitHub

Used by

git-mastery.org CS2103T Website