A reader should be able to install the CMS, learn the six product ideas, finish a task, look up a contract, or change the engine — and each of those is a different section. This guide is where a new page is allowed to live, and how to write it.

Jump to your section:

• Where a page belongs — the map, and the rule that keeps it from rotting.
• For all contributors — tone, style, and writing approach.
• For developers and agents — rules, frontmatter, and the pull request.

For All Contributors

You don’t need to be a developer to improve SveltyCMS documentation. Typo fixes, clarity improvements, and outdated screenshots are just as valuable as new API references.

Where to Start

• Typos & Grammar: Every fix counts. If you spot it, fix it.
• Clarity: If a step confused you, it will confuse others. Rewrite it.
• Outdated Info: If the UI or API response differs from the docs, open an issue or a PR.
• Missing Examples: If you solved a problem not covered in the docs, add it.
• Broken Links: If a relative link leads to a 404, update it.

The “User-First” Writing Approach

Structure every section in this order:

1. The Goal — What is the reader (Content Creator, Admin, or Developer) trying to achieve? State it in one sentence.
2. The Solution — Clear, step-by-step instructions (screenshots, code snippets) to achieve that goal.
3. The Mechanics — (Optional & Final) — Explain architecture, state machines, or DB-agnostic adapters after the goal is achieved. Never lead with mechanics for end-user guides.

🇪🇺 EU & German Comparative Advertising Compliance

All competitive comparisons in public-facing documentation must comply with EU Directive 2006/114/EC and German UWG §6 (Unfair Competition Act):

• Use Verifiable Sources: Every competitive claim must cite public, objective sources (competitor documentation, CVE databases, published benchmarks).
• Date-Stamp Performance Metrics: Include measurement date, hardware specs, and reproduction commands.
• Avoid Disparaging Language: Describe architectural differences neutrally (e.g., “React VDOM reconciliation” vs. “Svelte compile-time reactivity”). Never use terms like “fails to”, “broken”, or “suffers from”.
• Qualify Absolutes: Claims like “first”, “best”, or “only” must be qualified: “to our knowledge” or “based on public documentation as of [Date]“.
• Like-for-Like Comparisons: Only compare goods meeting the same needs. Note differences (SaaS vs. self-hosted, free vs. enterprise).

Writing Style

• Voice: Professional, direct, concise. Use American English.
• Active voice: “Click Save” not “The Save button should be clicked.”
• Short sentences: One idea per sentence.
• Real examples: Every concept should have a working code snippet or step-by-step scenario.
• Scannable structure: Use H2/H3 headings. End each section with a clear next step or summary.
• Headings: Use sentence case for headings (“Getting started with collections” not “Getting Started With Collections”).

When to Use a Mermaid Diagram

Use a diagram when the relationship between three or more components is not immediately obvious from prose alone. Do not add decoration-only diagrams.

Good candidates: Authentication flows, middleware pipelines, provisioning sequences, state machines, cache layers.

Skip the diagram: For a single API endpoint, a two-step process, or anything a one-sentence description handles clearly.

MDX Formatting Features

GitHub-Style Alerts

Use these callouts sparingly — if everything is important, nothing is.

> [!NOTE]
> General information that provides useful context.

> [!TIP]
> A helpful shortcut or best practice.

> [!IMPORTANT]
> An essential requirement the user must not miss.

> [!WARNING]
> A potential pitfall or side effect to be aware of.

> [!CAUTION]
> A high-risk action that may cause data loss or breakage.

Mermaid Diagrams

Use fenced code blocks with the mermaid language tag:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant DB
    Client->>API: Request + Token
    API->>DB: Verify & Query
    DB-->>API: Data
    API-->>Client: JSON Response
```

The renderer supports these diagram types: graph (flowchart), sequenceDiagram, classDiagram, stateDiagram, erDiagram, gantt, pie, gitgraph, mindmap, timeline, quadrantChart, xychart-beta, journey.

Code Blocks

Always specify the language for syntax highlighting:

```typescript
// TypeScript example
const result = await cms.collections.find("posts", { tenantId });
```

```bash
# Shell example
bun run dev
```

For code blocks that contain triple backticks, use quadruple backticks as the fence:

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

Enterprise benchmark reports (auto-generated)

Per-database reports in docs/project/benchmarks/benchmark_<db>.mdx use a progressive-disclosure dashboard — not hand-written prose. The canonical pipeline reference is Database Performance Benchmarks.

Dimension groups (ledger + executive rollups): Core, API, Scale, Resilience — marked with <!-- LEDGER_DIMENSION:CORE|API|SCALE|RESILIENCE:START/END -->.

Record modes:

HTML <details> in benchmark reports: Nested collapsibles are required for enterprise ledger UX. This is intentional for auto-generated benchmark MDX only — avoid raw HTML collapsibles in hand-written guides unless necessary.

Validate report shape after benchmark runs:

bun run lint:benchmark-mdx

For Developers and AI Agents {#for-developers}

This section contains non-negotiable rules. All PRs are checked against these standards before review.

⚠️ The Golden Rules

These rules are enforced. A PR that violates them will not be merged.

1. MDX Only, Correct Locations: All documentation files must be .mdx. No .md files. Files must live in their designated canonical location (see the table below) — no exceptions.

   Exception: Benchmark reports in docs/project/benchmarks/ are auto-generated by scripts/benchmark-matrix/generate-benchmark-reports.ts using an underscore naming convention (benchmark_sqlite.mdx, benchmark_postgresql_redis.mdx). This pipeline-driven naming is intentional and exempt from the kebab-case rule. Do not rename these files manually.

2. Centralized API Docs: All API documentation must live in docs/reference/api/. API content scattered elsewhere will be rejected.

3. Current Functionality Only: Document only what exists in the current codebase on the next branch. Do not document planned features, unmerged branches, or aspirational behavior.

4. Comprehensive Indexing: Index pages (e.g., docs/reference/api/index.mdx) must serve as a complete map. They must link to every child document in their category. A partial index is broken navigation.

5. Assets in static/docs/: All non-MDX assets (images, SVGs, diagrams) must be placed in static/docs/ and referenced via absolute project-root paths. No assets in docs/ itself.

6. Widget API Sync Rule: Any change to src/routes/api/[...path]/handlers/system.ts (the widgets section) or src/stores/widget-store.svelte.ts — adding, removing, or renaming a handler, or changing a response shape — must update docs/reference/api/system.mdx in the same PR. Refresh the updated date, update the endpoint table, and remove any obsolete entries.

7. Thin API Handler Pattern: Handlers in src/routes/api/[...path]/handlers/ must only parse the request, delegate to locals.cms (the Local SDK), and return a JSON response. All data access logic should live in the Local SDK (src/services/sdk/index.ts) or a dedicated service. Handlers that contain inline business logic will be rejected.

   // ✅ Correct — thin handler delegating to Local SDK
   export async function handleCollectionFind(event: RequestEvent) {
     const { locals, params } = event;
     const { id } = params;
     const entries = await locals.cms.collections.find(id, { tenantId: locals.tenantId });
     return successResponse(entries);
   }

8. Local SDK Performance Emphasis: When adding or modifying core CMS functionality, ensure it is exposed through the LocalCMS class (src/services/sdk/index.ts). Documentation for these features must highlight the performance advantage of using the Local SDK (zero HTTP overhead, direct DB adapter access) over external HTTP calls.

9. “Next Steps” Footer Required: Every guide, tutorial, and architecture page must end with a ## Next Steps or ## Related section linking to 2-3 relevant pages. This keeps readers flowing through the docs. A page that dead-ends at the last paragraph will be rejected.

10. Frontmatter updated Date: Update the updated field in frontmatter with every content change. Stale dates erode trust. The date must be in YYYY-MM-DD format.

11. One question, one page: A task is a guide. A contract is a reference page. An engine explanation is architecture. The product model stays in docs/concepts.mdx and stays short. Do not copy the same explanation into a second folder.

Where a page belongs {#where-a-page-belongs}

The docs follow the reader’s question. One page answers one question. Do not add a second copy of the same explanation in another folder.

Do not add a new top-level folder. Do not paste a full file tree into this guide. A pasted tree went stale while the files kept moving, and the index page of each folder is the map. That index must link every child document (golden rule 4).

Concepts stay short. A procedure belongs in a guide. A parameter table belongs in reference. A module layout belongs in architecture.

Architecture is not onboarding. Write those pages for someone changing that subsystem. Point a newcomer at Concepts.

Public URLs

docs.sveltycms.com serves this tree. The URL is /docs/ plus the path under docs/, without .mdx.

The site homepage has to use those paths. /docs/architecture, /docs/api, and /docs/widgets are not files. The pages that exist are /docs/reference/architecture, /docs/reference/api, and /docs/development/widgets.

Folders

Benchmark reports named docs/project/benchmarks/benchmark_*.mdx are generated. Do not rename them, and do not edit the marked zones by hand. The pipeline is Database performance benchmarks.

Frontmatter Specification

Every .mdx file must begin with a complete YAML frontmatter block. All fields are required.

Correct frontmatter example:

---
path: "docs/reference/api/collections.mdx"
title: "Collections API"
description: "REST API for managing content entries with multi-tenant isolation."
order: 15
icon: "mdi:database"
author: "your-github-handle"
created: "2026-01-10"
updated: "2026-03-27"
tags:
  - "api"
  - "collections"
  - "crud"
  - "rest"
---

Asset Management

All non-MDX files (images, screenshots, SVGs) must follow these rules:

• Location: static/docs/ — mirror the docs/ directory structure beneath it.
  • Example: An image for docs/reference/api/collections.mdx belongs in static/docs/reference/api/.
• Reference: Always use absolute paths. The static/ prefix is omitted because SvelteKit serves static/ at the root:

  ![SveltyCMS demo screenshot](/docs/SveltyCMS-Demo1.png)

File standards:

Pull Request Workflow

Documentation is treated with the same rigor as code. Every contribution passes through the same gates before it reaches next.

1. Branch: Create a branch with a descriptive name:

   git checkout -b docs/fix-collection-api-filter-params

2. Verify source alignment: If documenting code behavior, open the relevant file in src/ and confirm every parameter name, return value, and sequence matches what you have written.

3. Lint: Run the documentation linter and fix all errors before pushing:

   bun run lint-docs
   bun run slop

4. Audit & CI parity: Run the full check suite if code changed alongside docs:

   # Pre-commit checks (staged files, ~2-3s)
   bun run gate:fast
   
   # Pre-push checks (type check + unit tests, ~15-45s)
   bun run gate
   
   # Full CI simulation locally
   bun run test:doctor
   
   # Performance audit (if applicable)
   bun run scripts/benchmark-matrix/index.ts --parallel=safe

5. Update updated field: Change the date in frontmatter to today’s date.

6. Submit PR: Use a clear title following the convention:

   docs: add filter operator reference to SCIM API
   docs: fix outdated widget sync steps in troubleshooting
   docs: overhaul getting-started for user-first structure

7. AI agent commits: Commit messages authored or co-authored by AI agents must not include Co-Authored-By or AI-attribution tags. All commits should appear as the author’s own work for clean enterprise integration.

Pre-Submission Checklist

Before opening a PR, verify every item:

File & Frontmatter

• File is .mdx format — not .md
• File is in its correct canonical location
• path field in frontmatter matches the actual file location exactly
• All required frontmatter fields are present and correctly typed
• updated field reflects today’s date
• Content documents only current, existing functionality (nothing aspirational)

Technical Accuracy

• Every parameter name, endpoint path, and return value verified against src/
• Code examples are tested and functional
• Import paths in code examples are correct (use @src/, @utils/, @services/ aliases)
• Permission names match actual code (collections:read, not collection:read)

Assets & Links

• Images are in static/docs/ with mirrored directory structure
• All asset references use absolute paths from project root (/docs/...)
• Alt text provided for every image
• Internal links are correct and resolve to existing files
• “Next Steps” or “Related” section present at the bottom

Linting & CI

• Tags are lowercase and kebab-case
• Linter passes: bun run lint-docs and bun run slop
• Test suite passes: All unit tests are green (bun run test:unit)
• If docs/project/benchmarks/benchmark_*.mdx changed: changes came from the pipeline (not manual zone edits) and bun run lint:benchmark-mdx passes
• If src/stores/widget-store.svelte.ts or widget handler changed: docs/reference/api/system.mdx updated in this same PR
• Rendered correctly in the CMS preview (no broken mermaid, no stray formatting)

Questions and Support

• Unclear guidelines: Ask in GitHub Discussions
• Documentation bugs: Open a GitHub Issue
• PR review help: Tag a maintainer in your pull request

Related Documents

• Concepts
• Documentation hub
• Code of Conduct
• Contribution Guidelines
• API Documentation
• Admin Style Guide
• Widget Development Guide
• Validation Pipeline
• Database Performance Benchmarks