Skip to content
Docs-as-Code Blueprint

Authoring Workflow & Best Practices

While Sveltia CMS provides a clean, visual interface for content creation, maintaining a high-tier Docs-as-Code knowledge base requires discipline. Because every save directly modifies underlying Markdown and MDX files in your Git repository, following consistent authoring patterns ensures your pages render cleanly and pass all automated CI checks.

Daily Authoring Lifecycle

Section titled “Daily Authoring Lifecycle”

When a subject matter expert or writer contributes to the knowledge base, they follow a streamlined four-step publishing routine:

  1. Log In to the Admin Panel Navigate to your deployment URL (/admin/) and authenticate securely using your GitHub account.
    1. Select or Create a Document Choose an existing article from the Architecture Guides or Component Library collections, or click New Article to start fresh.
    2. Draft with Structure Input your frontmatter metadata (title, description) and compose the core content using the rich-text editor or raw Markdown mode.
    3. Publish & Trigger PR Click Publish. Sveltia CMS automatically commits the changes to a new branch and opens a pull request for automated review.

Authoring Dos and Don’ts

Section titled “Authoring Dos and Don’ts”

To prevent build failures and keep styling uniform across the entire documentation site, keep these core rules in mind:

DO: Keep Titles Concise

Ensure article titles are clear and descriptive. The title automatically populates the page header and the site sidebar navigation.

DON'T: Break Frontmatter

Never delete or alter required frontmatter fields like title or description. Missing fields will cause the Astro content schema validation to fail in CI.

DO: Use Markdown for Formatting

Rely on standard Markdown headers (##, ###), bullet points, and blockquotes rather than hardcoding HTML elements.

DON'T: Bypass Code Blocks

When including code snippets, always specify the programming language (e.g., ```javascript) so syntax highlighting renders correctly.

Section titled “Creating Internal Links”

Linking between guides and component documentation creates a cohesive reading experience. In Sveltia CMS, you can easily link to existing articles without having to memorize or copy-paste route paths:

Creating standard markdown links inside body prose.

  1. Highlight any word or phrase in the editor and click the Link icon in the toolbar (or press Cmd+K / Ctrl+K).
  2. In the link dialog, use the Pick from Existing Articles section at the top.
  3. Type in the filter box to quickly search by article title, section, or keyword.
  4. Select the target article from the dropdown. Sveltia CMS automatically fills in the exact route URL (e.g., /guides/voice-tone-accessibility/) and sets the link text if none was pre-selected.
  5. Optionally toggle Open link in a new window if you wish the link to open in a new browser tab (automatically pre-checked for external URLs).
  6. Click Insert or press Enter to place the link.

Handling Media Assets

Section titled “Handling Media Assets”

Images and diagrams are critical for effective technical documentation. Sveltia CMS handles media uploads seamlessly through its built-in asset manager:

  • Dropping images directly into the CMS.

When you upload an image via the media field, Sveltia automatically places the asset inside your project’s src/assets/ folder. This allows Astro’s image optimization pipeline to compress, resize, and convert the graphic into modern formats (like WebP) during build time.