Skip to content
SisterShield

Editing Guide for Maintainers

The SisterShield documentation site is built with Astro Starlight, a documentation framework built on Astro. This guide covers everything a maintainer needs to know to edit existing pages, add new content, and build the site.

File Structure

docs-site/
  astro.config.mjs         -- Astro + Starlight configuration (sidebar, locales, social)
  package.json              -- Dependencies and scripts
  src/
    content/
      docs/
        en/                 -- English content
          introduction/     -- Project introduction pages
          technical-docs/   -- Technical documentation
          maintainers/      -- This guide
        ko/                 -- Korean content (mirrored structure)
    styles/
      custom.css            -- Custom CSS overrides

Each .md file in src/content/docs/ corresponds to a page in the documentation site. The file path determines the URL: en/technical-docs/architecture/overview.md maps to /docs/technical-docs/architecture/overview/.

How to Edit a Documentation Page

  1. Open the relevant .md file in docs-site/src/content/docs/en/ (or ko/ for Korean).
  2. Edit the Markdown content. Every file must begin with a frontmatter block:
---
title: "Page Title"
description: "Short description for SEO and link previews."
---
  1. Save the file. If the dev server is running, changes are reflected immediately via hot reload.

How to Add a New Page

Step 1: Create the Markdown File

Create a new .md file in the appropriate directory under src/content/docs/en/. For example, to add a new page under Technical Docs:

docs-site/src/content/docs/en/technical-docs/new-topic.md

Add the required frontmatter:

---
title: "New Topic"
description: "Description of this new topic."
---

Step 2: Add to the Sidebar

Open docs-site/astro.config.mjs and add an entry to the sidebar array in the appropriate section:

{
  label: 'New Topic',
  translations: { ko: 'Korean label here' },
  link: '/technical-docs/new-topic/',
},

The link value must match the file path relative to src/content/docs/en/, with leading / and trailing /.

Step 3: Create the Korean Version (Optional)

Create the same file at docs-site/src/content/docs/ko/technical-docs/new-topic.md with Korean content. If no Korean version exists, Starlight will fall back to the English version.

How to Add a New Locale

Starlight supports multiple locales. To add a new language:

  1. Register the locale in astro.config.mjs:
locales: {
  en: { label: 'English', lang: 'en' },
  ko: { label: '한국어', lang: 'ko' },
  ja: { label: '日本語', lang: 'ja' },  // new locale
},
  1. Create the content directory: docs-site/src/content/docs/ja/.
  2. Add translated files mirroring the en/ structure. Any missing files will fall back to the default locale (English).
  3. Add translations entries to sidebar items in astro.config.mjs.

How to Add Mermaid Diagrams

Mermaid diagrams are written inside fenced code blocks with the mermaid language tag:

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

Supported diagram types: graph/flowchart, sequenceDiagram, classDiagram, stateDiagram-v2, erDiagram.

How to Use Starlight Callouts

Starlight provides built-in callout components using the ::: syntax:

:::note
This is an informational note.
:::


:::tip
A helpful tip for the reader.
:::


:::caution
A warning about something to be careful with.
:::


:::danger
A critical warning about something that could cause problems.
:::

These render as styled callout boxes with appropriate colors and icons.

How to Use Starlight Components

Starlight includes several built-in components that can be imported in MDX files. For standard Markdown (.md), the ::: callout syntax is the primary component mechanism.

For MDX files (.mdx), you can import Starlight components:

import { Tabs, TabItem } from '@astrojs/starlight/components';


<Tabs>
  <TabItem label="npm">npm install</TabItem>
  <TabItem label="pnpm">pnpm install</TabItem>
</Tabs>

How to Build and Preview Locally

Development Server

Terminal window
cd docs-site
npm install
npm run dev

The site runs at http://localhost:4321/docs/. Changes to .md files trigger hot reload.

Production Build

Terminal window
cd docs-site
npm run build

The output is generated in docs-site/dist/. Preview the built site:

Terminal window
npm run preview

Content Rules

  1. Evidence-first: Every claim must be traceable to the codebase or a cited source. Do not invent statistics.
  2. TODO placeholders: Mark incomplete content with TODO: (e.g., TODO: Add benchmarks).
  3. Code accuracy: File paths and function names must match the actual codebase.
  4. Keep current: Update docs when the codebase changes.
  5. No emojis: Use standard punctuation and formatting only.

Quick Reference: Common Tasks

TaskSteps
Fix a typoEdit the .md file, save
Add a new section to existing pageEdit the .md file, add heading + content
Add a new pageCreate .md file + add to sidebar in astro.config.mjs
Add a diagramUse ```mermaid code block
Add a calloutUse :::note / :::tip / :::caution / :::danger syntax
Remove a pageDelete the .md file + remove from sidebar in astro.config.mjs
Change sidebar orderReorder items in the sidebar array in astro.config.mjs
Add Korean translationCreate matching file in ko/ directory