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 as: NUS · Reset

<cv-insertion insertion-id="week1-preamble">

*No institution-specific note for this section.*

</cv-insertion>

<cv-insertion insertion-id="week2-preamble">

*No institution-specific note for this section.*

</cv-insertion>

    

    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.

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 for the lookup key for the <cv-insertion insertion-id="..."> element, while the matching <div id="..."> block in insertions.html uses id as the lookup key. This is because standard id attributes must be unique per page. This allows you to safely reuse the same insertion point multiple times without breaking HTML validation or browser anchor routing.

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>NUS CS2103T 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" label="week 2" 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.

Attributes of <cv-insertion>

Slot (default content): Any children inside <cv-insertion> are rendered when no adaptation is active, or when the active adaptation has no matching id in its insertions.html.

Attributes of <div> (in insertions.html)

With Attribution Label

Use the label attribute to override the attribution label shown in the callout header for a specific insertion point. When omitted, the label defaults to the adaptation's name field from its JSON config.

With Custom Color

Use the color attribute to override the color of the callout box and its label. This is useful for color-coding specific insertions (e.g. red for deadlines, green for tips). You can provide any valid CSS color, including hex codes like #ef4444.

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

When omitted, the color defaults to the active adaptation's --cv-primary theme color.

No Default Content

If an insertion point has no meaningful default, you can use a self-closing tag. The element renders nothing when no matching block is found:

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

    

    Copy
    

    


    
    
    
    

    Wrap Text
    

    


    
    
    

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 default attribution label in all <cv-insertion> callout headers for this adaptation (unless overridden per-tag via name attribute).

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, or override it per-tag with the label attribute on <cv-insertion>.