SveltyCMS

Documentation

Contributing to the Documentation

A comprehensive guide on how to contribute to the SveltyCMS documentation.

Last updated: 11/14/2025

Documentation Contribution Guide

High-quality documentation is the backbone of SveltyCMS. This guide provides a clear, actionable framework for all contributors—both human and AI—to create consistent, high-quality content.

The Golden Rules: Core Principles

All contributions must adhere to these foundational rules.

  1. MDX Only & Correct Locations: All documentation files must be .mdx files and placed only in their designated canonical locations (see below).
  2. Centralized API Docs: All API documentation must be located in /docs/api/ to provide a single, unified reference.
  3. Current Functionality Only: Document only what exists in the current codebase. Do not add documentation for planned features or unmerged changes.
  4. Assets in /static/docs: All non-MDX assets (images, diagrams) must be placed in /static/docs/ and referenced via an absolute path.
  5. Widget API Sync: Any change to src/routes/api/widgets/ or src/stores/widget-store.svelte.ts (add/remove/rename endpoint, response shape change) MUST update /docs/api/Widget_API.mdx in the same PR (refresh updated, status table, remove obsolete endpoints). Never leave docs out-of-sync.

Canonical Documentation Locations

To eliminate ambiguity, all documentation must be placed in one of the following locations. No other locations are permitted.

1. API Documentation → /docs/api/

  • What: The complete reference for all REST API endpoints.
  • Where: /docs/api/
  • Why: Centralizes the entire API surface in one place for a holistic, easy-to-navigate user experience.

2. Widget Documentation → src/widgets/...

  • What: Documentation for a specific widget.
  • Where: src/widgets/core/[widget-folder]/[widget-name].mdx
  • Why: Co-locating documentation with the widget’s source code makes it self-contained and easier to maintain.

3. General Documentation → /docs/...

  • What: All other guides, tutorials, and explanations (including this one).
  • Where: Sub-folders within /docs/ (e.g., /docs/guides/, /docs/contributing/).
  • Why: Provides a central library for all topic-based information that isn’t tied to a specific widget or API endpoint.

Instructions for Documentation Creation

To maintain consistency and quality, all contributors should adhere to the following workflow and rules.

Guiding Principles

  • Act as an Expert: Write as an expert technical writer for the SveltyCMS project.
  • Goal: Produce clear, accurate, and perfectly formatted documentation that is easy for all users to understand.
  • Voice: Professional, direct, and concise. Use American English.

Authoring Workflow

  1. Analyze Context: Before writing, thoroughly analyze the request, existing code, and related documentation to understand the goal.
  2. Adhere to Rules: Follow all rules in this guide, especially the Golden Rules and the Frontmatter Guide.
  3. Write Content: Create the MDX content, focusing on clarity, accuracy, and practical examples.
  4. Validate Frontmatter: Ensure the YAML frontmatter is complete, correct, and matches the file’s location and content.
  5. Verify Paths: Double-check that all asset and internal links use correct, absolute paths.

Core Authoring Rules

  • ALWAYS place documentation in the correct canonical location as defined above.
  • ALWAYS ensure the path field in the frontmatter is the exact, full path of the file from the project root.
  • NEVER create .md files. Only create .mdx files.
  • NEVER place images or other assets anywhere except /static/docs/.

Documentation Structure Example

This example shows the correct placement for different types of documentation.

# 1. General and API documentation in /docs
docs/
├── api/                              # API docs are ONLY here
│   ├── index.mdx                     # API overview and authentication guide
│   └── Authentication_2FA_API.mdx    # Two-factor authentication endpoints
│   ├── Collection_API.mdx            # Collection CRUD operations
│   ├── User_Token_Management_API.mdx # User and token management
│   ├── Widget_API.mdx                # Widget management endpoints
│   ├── Settings_API.mdx              # System settings endpoints
│   ├── Media_API.mdx                 # Media upload and management
│   └── ...                           # Other core Apis
│
└──  contributing/                    # Contributor documentation
    ├── contributing-docs.mdx         # This file
    ├── code-of-conduct.mdx           # Code of conduct
    └── pull-requests.mdx             # PR guidelines

# 2. Widget documentation in /src/widgets per Widget
src/
└── widgets/                          # All widget documentation
│   ├── index.mdx                     # Widget system overview & 3-pillar architecture
│   ├── Creating_Custom_Widgets.mdx   # Guide for creating widgets
│   ├── Widget_Management_System.mdx  # Management features & lifecycle
│   ├── Widget_Marketplace_System.mdx # Marketplace integration
│   └── core/                         # Individual core widget docs
│       ├── text.mdx                  # Text input widget
│       ├── richText.mdx              # Rich text editor widget
│       ├── mediaUpload.mdx           # Media upload widget
│       ├── relation.mdx              # Relation widget
│       └── ...                       # Other core widgets

Frontmatter Guide

Every MDX file must begin with a YAML frontmatter block enclosed by --- lines. This metadata is critical for navigation, search, and display.

Required fields

Field Required Purpose Example Value
path Yes Full path from project root. Used for routing and identification. "docs/api/Authentication_2FA_API.mdx"
title Yes Main heading (H1). Shown in navigation, browser tab, and search results. "Two-Factor Authentication API"
description Yes One-sentence summary for SEO and previews. "Complete 2FA API endpoint reference."
order Yes Position in sidebar navigation relative to siblings. Lower numbers appear first. 2
icon Yes Material Design Icon with mdi: prefix. "mdi:shield-lock"
author Yes GitHub username of original author. "admin"
created Yes Creation date in YYYY-MM-DD format. "2025-10-05"
updated Yes Last significant update date. Update with every meaningful change. "2025-10-05"
tags Yes Array of relevant keywords for search and filtering. Use lowercase, kebab-case for multi-word. ["api", "authentication", "2fa", "totp"]

Managing Assets (Images, Diagrams, Videos)

All non-MDX files must be placed in the /static/docs/ directory to keep documentation folders clean.

Rules

  • Location: /static/docs/
  • Structure: Mirror the /docs/ directory structure
  • Example: Image for /docs/api/Authentication_2FA_API.mdx goes in /static/docs/api/

Referencing Assets

Always use absolute paths from the root:

![2FA Setup Flow](/docs/api/2fa-setup-flow.png)

Asset Guidelines

  • Formats: PNG for screenshots, SVG for diagrams/icons
  • Optimization: Keep files under 500KB
  • Naming: Use descriptive kebab-case names (e.g., api-authentication-flow.svg)
  • Alt Text: Always provide meaningful alt text for accessibility

Content Best Practices

Writing Style

  • Clarity: Use active voice, short sentences, plain language
  • Structure: Start with intro, use H2/H3 headings, end with summary or next steps
  • Examples: Provide practical code snippets and real-world examples
  • Consistency: Follow existing doc style. Use American English.
  • Accessibility: Add alt text, ensure good contrast, make content scannable

MDX-Specific Guidance

  • Basic Markdown: Use standard syntax (bold, italics, lists, links, code blocks with language tags)
  • Code Blocks: Always specify language for syntax highlighting:
```typescript
// TypeScript code here
```
  • JSX Components: Use sparingly, only for interactive elements
  • Escaping: Use backticks or HTML entities (<, >) for literal angle brackets

Review and Update Process

Pull Request Workflow

  1. Create Branch: Make documentation changes in a feature branch
  2. Run Linter: Execute bun ./docs/lint-docs.ts and fix any errors
  3. Submit PR: Create pull request with descriptive title
  4. Review: Reviewers check for accuracy, clarity, and adherence to guidelines
  5. Update updated field: Change the date in frontmatter
  6. Merge: Once approved, changes are merged

Updating Existing Docs

  • Always update the updated field in frontmatter
  • Keep changes focused on one topic per PR
  • Add a commit message explaining what changed

Versioning

  • Documentation is versioned with the code
  • Major changes may need release notes
  • Breaking API changes must be documented immediately

Checklist for New Documentation

Before submitting a PR:

  • Correct Location: The file is in its designated canonical location.
  • Frontmatter is complete with all required fields.
  • path field matches actual file location.
  • Content is clear, accurate, and follows best practices.
  • Code examples are tested and working.
  • Assets are in /static/docs/ with correct structure.
  • File is .mdx format (not .md).
  • Linter passes: bun ./docs/lint-docs.ts.
  • updated field reflects current date.
  • If widgets API or store changed: docs/api/Widget_API.mdx synced (status table & removed endpoints handled).
  • Tags are relevant and lowercase/kebab-case.
  • Links to other docs use correct paths.
  • Tested rendering in the CMS (if possible).

Tools and Validation

Frontmatter Linter

To ensure all documentation is valid, run the linter before submitting a pull request. This tool checks files in both docs/ and src/widgets/.

bun ./docs/lint-docs.ts

This tool validates all .mdx files, reports errors, and identifies any .md files that need to be converted. A passing linter is a requirement for merging.

The linter will:

  • ✅ Validate all .mdx files in docs/ and src/widgets/ directories
  • 🔍 Detect .md files that need conversion to .mdx
  • ❌ Report frontmatter errors with helpful messages
  • 📊 Display summary with validation results

Always run the linter before submitting a PR.

Questions and Support

  • Documentation Issues: Open an issue on GitHub
  • Unclear Guidelines: Ask in GitHub Discussions
  • Contribution Help: Tag maintainers in your PR

Related Documents

documentationcontributingmdxguide