SveltyCMS

Documentation

Contributing to the Documentation

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

Last updated: 10/9/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.

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.
  • 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