Skip to content
Docs-as-Code Blueprint

Inserting Custom Components (CMS Magic)

One of the greatest superpowers of our Docs-as-Code setup is that writers can drop rich, interactive UI components directly into documents without writing complex React, Astro, or HTML markup.

In Sveltia CMS, these components are registered as Custom Editor Shortcodes. When you insert one, Sveltia presents an easy-to-use form with clear input fields, dropdown menus, and validation rules.

How to Insert Components in Rich Text Mode

Section titled “How to Insert Components in Rich Text Mode”

Inserting any custom component takes just three steps:

  1. Open the Insert Menu:
    In the editor toolbar, click the + (Add Block) dropdown button (or press Slash (/) on an empty line if quick-insert is enabled).
  2. Select Your Component:
    Choose from the registered components list: Aside / Callout, Steps, Tabs, Badge, File Tree, or Link Card.
  3. Populate the Form Fields:
    Fill in the generated form fields (e.g., choosing a color variant or typing content). Sveltia immediately renders a live preview block inside your editor.

Available Custom Components

Section titled “Available Custom Components”

Explore the six custom editor components available in Sveltia CMS:

1. Starlight Aside / Callout (<Aside>)

Section titled “1. Starlight Aside / Callout (<Aside>)”

Use asides to call out critical notes, tips, warnings, or danger notices without breaking the flow of your document.

  • Type (Select Dropdown): Choose note (purple), tip (green), caution (yellow/orange), or danger (red).
  • Title (Optional Text Input): Overrides the default label (e.g., “Important Requirement” instead of “CAUTION”).
  • Callout Content (Markdown Area): Type your message using standard Markdown (bold, links, inline code).

🔍 Deep Dive Specimen: For live examples of all four color variants and custom title overrides, explore the Callouts & Asides Specimen.

2. Dual-Tab Switcher (<Tabs>)

Section titled “2. Dual-Tab Switcher (<Tabs>)”

Use tabs to present alternative workflows side-by-side (such as macOS vs. Windows instructions, or Terminal commands vs. GUI steps).

  • Tab 1 Label: Heading for the first tab (e.g., macOS / Linux).
  • Tab 1 Content: Content displayed inside the first tab.
  • Tab 2 Label: Heading for the second tab (e.g., Windows).
  • Tab 2 Content: Content displayed inside the second tab.

🔍 Deep Dive Specimen: For advanced multi-tab patterns and tab-syncing behavior, explore the Tabs & Switchers Specimen.

3. Numbered Sequential Steps (<Steps>)

Section titled “3. Numbered Sequential Steps (<Steps>)”

Use steps for procedural tutorials where order is paramount. Starlight automatically converts standard ordered lists into high-visibility circled number badges.

  • Ordered Steps (Markdown Area): Enter your steps as a standard Markdown numbered list: 
    1. Open the project dashboard.
    2. Click the **Publish** button.
    3. Verify the deployment preview.

🔍 Deep Dive Specimen: For complex procedural hierarchies, explore the Procedural Steps Specimen.

4. Status Badges (<Badge>)

Section titled “4. Status Badges (<Badge>)”

Use badges to highlight feature versions, draft flags, or API status indicators inline.

  • Badge Text: The label displayed inside the badge (e.g., v2.0, Required, Beta).
  • Color Variant (Select): default, note, tip, caution, danger, or success.
  • Size (Select): small, medium, or large.

🔍 Deep Dive Specimen: For all size variations, color schemes, and header usage patterns, explore the Badges & Status Indicators Specimen.

5. Directory File Trees (<FileTree>)

Section titled “5. Directory File Trees (<FileTree>)”

Use file trees to visualize repository directory structures, project layouts, or file organization.

  • File Tree Structure (Markdown Area): Enter directory names with trailing slashes and files as indented list items: 
    - src/
      - content/
        - docs/
          - index.mdx
      - assets/
        - logo.png
    - package.json

🔍 Deep Dive Specimen: For file trees with bold targets and inline comments, explore the File Trees Specimen.

Section titled “6. Starlight Link Card (<LinkCard>)”

Use link cards to provide prominent, beautifully styled cards that direct readers to the next logical article or reference guide.

  • Target Article (Searchable Dropdown): Pick an existing article from across the entire site. The CMS automatically fills the route URL!
  • Card Title (Optional): Overrides the destination article title.
  • Card Description (Optional): Overrides the destination article teaser description.

🔍 Deep Dive Specimen: For multi-column card grids and regular informational cards, explore the Cards & LinkCards Specimen.

Additional Visual Components Available to Writers

Section titled “Additional Visual Components Available to Writers”

Beyond the registered CMS shortcodes, Starlight includes several built-in visual elements you can incorporate when authoring in raw Markdown or MDX mode:

Icon Reference & Catalog

Browse over 200+ built-in Starlight SVG icons you can use in cards, tabs, and badges. Explore the Icon Catalog.

Expressive Code

Add file titles (title="app.js"), terminal frames, line highlights ({3-5}), and git diffs (+ / -). Explore Expressive Code.

Architecture Diagrams (Mermaid)

Create clean, version-controlled flowcharts, sequence diagrams, and mind maps with plain text. Explore Dynamic Architecture Diagrams.

FAQ Accordions

Create interactive, collapsible disclosure sections for frequently asked questions. Explore FAQ Accordions.

Component Usage Governance

Section titled “Component Usage Governance”

Before introducing multiple visual elements onto a single page, review our official Component Standards Guide for rules on avoiding callout fatigue, preserving responsive readability, and choosing the right visual component for your audience.