Site Adaptations

Site Adaptations

Adaptations let you ship pre-configured site variants — different branding and default content states — that activate for a specific audience from a single URL parameter.

Common use cases:

• A documentation site shared across multiple institutions, each with their own colour scheme and default content selections.
• A platform-specific landing page that pre-selects the relevant OS toggle for every visitor.
• A preview link sent to a client that activates their branded theme.

---

How It Works

An adaptation is a JSON file hosted alongside your site content. When a user visits a URL with ?adapt=<id> or a hash indicator like #/id (for example, https://example.com/#/dark), CustardUI fetches that file, applies the theme and state overrides, and persists the active adaptation to localStorage — so it remains active across all pages without the parameter or hash needing to be in every URL.

Activation priority (highest wins):

1. <meta name="cv-adapt" content="<id>"> on the page — forces a specific adaptation for that page on every visit
2. Explicit URL activation — ?adapt=<id> parameter or hash #/id indicator
3. localStorage — persisted from a previous activation

---

Quick Start

Step 1: Create the adaptation JSON file

Place the file at {baseUrl}/{id}/{id}.json. For a site with data-base-url="/docs" and adaptation id dark:

/docs/dark/dark.json

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Minimal example:

{
  "id": "dark",
  "theme": {
    "cssVariables": {
      "--cv-primary": "#7c3aed"
    }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Step 2: Link to it

<a href="?adapt=dark">Switch to dark theme</a>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

That's it. No script tag changes needed — the path is derived automatically from data-base-url.

---

File Placement

Adaptation JSON files are resolved relative to your site's data-base-url:

{baseUrl}/{id}/{id}.json

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The convention co-locates the adaptation JSON with any landing page content for that variant:

docs/
  nus/
    index.md       ← NUS landing page
    nus.json       ← adaptation config

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

---

Adaptation JSON Schema

{
  "id": "nus",
  "name": "NUS",
  "theme": {
    "cssVariables": {
      "--cv-primary": "#003d7c",
      "--cv-primary-hover": "#002d5c"
    },
    "cssFile": "/nus/nus-extra.css"
  },
  "defaults": {
    "toggles": {
      "linux": "show",
      "windows": "hide"
    },
    "placeholders": {
      "username": "NUS Student"
    }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Top-level fields

theme

defaults

Adaptation defaults are applied before the user's persisted state, so users can still override them from the settings modal.

Author-Controlled Placeholders (adaptationPlaceholder)

To define a placeholder that users cannot see or change — only adaptations and the config defaultValue can set its value — mark it with adaptationPlaceholder: true in custardui.config.json:

{
  "name": "institutionName",
  "defaultValue": "Generic University",
  "adaptationPlaceholder": true
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The adaptation then overrides it via defaults.placeholders:

{
  "id": "nus",
  "defaults": {
    "placeholders": { "institutionName": "NU Instutition" }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Example placeholder

\[[institutionName]] renders "NUS" for NUS visitors and "Generic University" for others. These values are never shown in the settings modal, never persisted to localStorage, and never included in shared links.

\[[ institutionName ]]:

• [[ institutionName ]]
• link to NUS adaptation,
• link to clear adaptation

---

State Layering Precedence

When determining the initial toggle state, CustardUI applies layers in this order:

---

Per-Page Activation

To activate a specific adaptation on a particular page — so that visiting the page always switches to that adaptation regardless of what is currently stored — add a meta tag to the page's <head>:

<meta name="cv-adapt" content="ntu">

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

In MarkBind, use the <head-bottom> tag:

<head-bottom>
  <meta name="cv-adapt" content="ntu">
</head-bottom>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

This is useful for institution-specific landing pages: visiting /nus/ always switches the visitor to the NUS theme, even if they previously had a different adaptation active.

---

Clearing an Adaptation

To deactivate the current adaptation and return to the site defaults, link to ?adapt=clear:

<a href="?adapt=clear">Reset to default theme</a>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

This removes the stored adaptation. On the next page load (without a page meta tag), no adaptation will be active.

---

Example: Institution Adaptation of this Site

For example, we want this documentation site to be customized for NUS.

docs/nus/index.md

<head-bottom>
  <meta name="cv-adapt" content="nus">
</head-bottom>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

docs/nus/nus.json

{
  "id": "nus",
  "theme": {
    "cssVariables": { "--cv-primary": "#003d7c" }
  },
  "defaults": {
    "toggles": { "linux": "show", "windows": "hide" },
    "placeholders": { "username": "NUS Student" }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Students linked to /nus/ get the NUS theme immediately; the theme persists as they navigate the rest of the site.

See the live demo for an interactive example.