Adding and Removing Sections

This guide describes how to create and remove sub-sections in the documentation site. You can use the Section Creator widget on the local dev server or work with the files manually.

Adding a Section

Using the Section Creator Widget

When running the site locally (npm run dev), the About page displays a Create New Section form at the top of the page. The widget is not present in the published site.

The form collects:

• Parent Section — where the new sub-section will be created, populated from the sidebar configuration.
• Title — the display title for the section’s landing page.
• Folder Name — optional. The directory name in kebab-case (e.g., my-new-section). If omitted, it is derived automatically from the title.
• Sidebar Order — controls the position within auto-generated sidebar sections (lower numbers appear higher).
• Domain — the top-level section this content belongs to.
• Maturity — lifecycle status (draft, review, published, proposed).
• Tags — comma-separated keywords for discoverability.

On submit, the widget:

1. Creates the directory under src/content/docs/<parent>/<folder>/.
2. Writes an index.md with the appropriate frontmatter.
3. Updates src/sidebar.json if the parent section uses explicit sidebar items (auto-generated sections pick up new directories automatically).
4. Shows a confirmation screen with the path to the new file. Click Done to return to the form.

Manual Procedure

Step 1: Create the directory and index file

Create a new directory with a kebab-case name under the parent section, and add an index.md:

src/content/docs/<section>/<new-subsection>/
└── index.md

The index.md must include the standard frontmatter:

---
title: "Sub-Section Title"
sidebar:
  order: 50
tags: [<section>, <topic>]
domain: <section>
maturity: published
author: "Arda Systems"
---

Add an introductory paragraph describing the sub-section’s scope.

Step 2: Add content pages

Create .md files inside the directory, one per topic:

src/content/docs/<section>/<new-subsection>/
├── index.md
├── first-topic.md
└── second-topic.md

Each page uses the same frontmatter pattern. Use sidebar.order to control ordering within the sub-section.

Step 3: Register in the sidebar

The sidebar configuration lives in src/sidebar.json. There are two patterns depending on how the parent section is configured:

Auto-generated parent — sections like domain, legal, technology, and decisions use autogenerate. New directories are picked up automatically with no configuration change needed.

Explicit parent — sections like product, process, and about have hand-crafted items arrays. Add an entry for the new sub-section:

{
  "label": "New Sub-Section",
  "collapsed": true,
  "autogenerate": { "directory": "<section>/<new-subsection>" }
}

Or for finer control over individual pages:

{
  "label": "New Sub-Section",
  "collapsed": true,
  "items": [
    { "slug": "<section>/<new-subsection>" },
    { "slug": "<section>/<new-subsection>/first-topic" }
  ]
}

Step 4: Deeper nesting (optional)

For sub-sub-sections, repeat the pattern — create a nested directory with its own index.md:

<new-subsection>/
├── index.md
├── standalone-page.md
└── nested-group/
    ├── index.md
    ├── page-a.md
    └── page-b.md

Step 5: Verify

Run npm run dev and check that the new section appears in the sidebar and renders correctly.

Removing a Section

There is no widget for removing sections — this is a manual procedure.

Step 1: Delete the content directory

Remove the section’s directory and all of its contents:

rm -rf src/content/docs/<section>/<subsection-to-remove>/

Step 2: Remove the sidebar entry

Open src/sidebar.json and find the entry for the removed section.

Auto-generated parent — no sidebar edit needed. The directory is gone, so Starlight will no longer generate sidebar entries for it.

Explicit parent — find and remove the corresponding object from the parent’s items array. For example, delete:

{
  "label": "Old Sub-Section",
  "collapsed": true,
  "autogenerate": { "directory": "<section>/<subsection-to-remove>" }
}

or any slug entries that reference paths under the removed directory.

Step 3: Fix broken links

Search the documentation for links pointing to the removed section:

grep -r '<subsection-to-remove>' src/content/docs/

Update or remove any references to prevent broken links in the published site.

Step 4: Verify

Run npm run dev and confirm:

• The removed section no longer appears in the sidebar.
• The site builds without errors (npm run build).
• No broken links remain (check the build output for warnings).