Adaptation Insertions

Insertions

<cv-insertion>

Insertions let adopters inject their own content at specific points in site pages — without modifying the original source. They are ideal for institution-specific preambles, deadline reminders, or notes before exercises that the original site author has designated as injectable.

View Adaptations: NUS · Reset to Default

<cv-insertion insertion-id="week1-preamble">
 <md>*No note for this section.*</md>
</cv-insertion>

<cv-insertion insertion-id="week2-preamble" align="justify" default-style="none">

*No note for this section.*
</cv-insertion>

<cv-insertion insertion-id="week3-note" outline="solid"/>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

When the active adaptation has a matching block in its insertions.html, the <cv-insertion> element renders it as a styled adopter callout. When there is no matching block — or no adaptation is active — the default slot content (children) is shown instead. By default, this fallback content is also rendered inside the same styled callout box to prevent layout shifts. The styling can be disabled.

Basic Syntax

<cv-insertion insertion-id="exercise-1-preamble">
  Default content shown when no insertion matches.
</cv-insertion>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

insertion-id attribute is used as the lookup key for the matching id of the <div id="..."> block in insertions.html. As id should be unique per page, this allows safe reuse of insertion points multiple times across a page.

Source insertions.html Format

Each adopter creates an insertions.html file in their adaptation folder. Each <div id="..."> element defines one injection block — the id is the lookup key and the innerHTML is what gets rendered.

insertions.html / insertions.md (for static site generators like MarkBind)

<!-- versions/org-a/insertions.html -->
<div id="week1-preamble">
  <p>
    <strong>Students:</strong> Before starting this section, make sure you have
    accepted the GitHub Classroom invitation and set up your individual project repository.
    Refer to the course schedule for this week's exact deadline.
  </p>
</div> 

<!-- versions/org-a/insertions.md (for MarkBind or SSGs):-->
<div id="week2-preamble" color="#ef4444">

Complete this right after Week 1's tasks. This exercise is **examinable** —
ensure you understand each step before proceeding.

</div>

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The insertion-id links the tag to a <div id="..."> in the adopter's insertions.html. When a match is found, the adopter's HTML replaces the default slot content and is wrapped in a labelled callout block.

• Only <div id="..."> elements are parsed in insertion.html. Other elements (paragraphs, comments, etc.) not contained in these div elements are ignored.
• You can include any HTML inside the <div> blocks: paragraphs, lists, bold text, links, etc.

Attributes of <cv-insertion>

Attributes of <div> (in insertions.html)

Component Rendering Behavior

The <cv-insertion> component behaves differently depending on the context:

1. Default / No Active Adaptation: When viewing the base site, the default content is rendered.
2. Active Adaptation with Matching <div id> in insertions.html: Div content is rendered inside the callout box.
3. Active Adaptation with No Matching insertion-id to <div id>: If an adaptation is active, but its insertions.html does not contain a div element with id corresponding to the insertion-id, nothing is rendered.

Alternatively, to use <cv-insertion> as a pure UI element that is never replaced, omit the insertion-id attribute. In this case, the component acts as a static UI wrapper that is never replaced, and will always render its default content across all adaptations.

Default Content in Insertions

When the default content is displayed, it is rendered inside a styled callout box by default (default-style="callout") so that the visual layout remains consistent with the adaptations. You can disable this by setting default-style="none" to render the fallback content completely unstyled/inline.

Setting no default content: If an insertion point has no meaningful default, you can use a self-closing tag. The element automatically renders nothing when there is no active adaptation enabled.

<cv-insertion insertion-id="week3-note" />

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

View in Adaptation: NUS · Reset to Default

File Placement

By default, CustardUI looks for insertions.html in the same folder as the adaptation's JSON config:

{baseUrl}/{adaptationsPath}/{id}/insertions.html

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The conventional layout keeps the insertions file alongside the adaptation config:

versions/
  org-a/
    org-a.json       ← adaptation config
    insertions.html  ← adopter insertions
    index.md         ← optional landing page

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

Custom Filename

To use a different filename, set insertionsFile in the adaptation's JSON config:

{
  "id": "org-a",
  "insertionsFile": "notes.html"
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

CustardUI will then fetch {adaptationsPath}/org-a/notes.html instead. If the field is omitted, insertions.html is used.

Adaptation Config

The insertionsFile field is optional and belongs at the top level of the adaptation JSON:

{
  "id": "nus",
  "name": "NUS",
  "insertionsFile": "insertions.html",
  "preset": {
    "toggles": { "nus-resources": "show" }
  }
}

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

The name field is used as the attribution label in all <cv-insertion> callout badges for this adaptation.

See Adaptation Configuration for the full JSON schema.

Troubleshooting

• Insertion not showing? Check that the insertion-id attribute on the tag exactly matches the id attribute on the <div> in insertions.html (case-sensitive).
• Default content showing instead of adopter block? Verify that the adaptation is active (#/id in the URL or ?adapt=id), and that insertions.html is accessible at the expected path.
• No content at all? If neither the adopter block nor the default slot content appears, ensure the <cv-insertion> tag has children for the fallback case, or check browser network tools to confirm the insertions file was fetched.
• Wrong attribution label? Set the name field in the adaptation's JSON config.