Quality Automation (CI/CD)

In a traditional documentation workflow, quality control is manual, error-prone, and relies entirely on human review. Typos slip into production, external hyperlinks rot over time, and formatting inconsistencies degrade the professional quality of the knowledge base.

This architecture replaces manual auditing with automated quality gates. Using GitHub Actions, every single pull request is automatically tested for prose style, link integrity, and build validity before a human ever clicks “Merge.”

The Automated Pipeline Architecture

Whenever a contributor pushes code or submits changes via Sveltia CMS, GitHub Actions fires off three parallel verification jobs:

Prose Linting (Vale) Scans all Markdown and MDX files against the Google Developer Style Guide to catch passive voice, jargon, and spelling inconsistencies.
1. Link Integrity Check (Lychee) Crawls every internal and external hyperlink across the site to ensure zero 404 errors or broken URLs exist.
2. Build & Frontmatter Validation (Astro + Zod) Performs a full static build of the site. If an author misses a required Zod frontmatter field (like title), the compiler throws an error and safely blocks the merge.

Behind the Configuration

Explore the implementation files that drive these quality checks behind the scenes.

Enforcing editorial standards using .vale.ini.

Vale analyzes natural language text just like a compiler analyzes source code. Our configuration points to the Google Style Guide to ensure concise, active, and accessible technical writing.

StylesPath = .vale/styles
MinAlertLevel = warning

[*.mdx]
BasedOnStyles = Google

# Custom overrides
Google.We = suggestion

Preventing link rot using lychee.toml.

Lychee is a fast, async link checker written in Rust. It scans all generated HTML output during CI to verify that referenced resources are online and responsive.

root_dir = "./dist"
verbose = "info"
accept = ["200..=204", "206", "429"]
timeout = 20
exclude_all_private = true

Orchestrating the pipeline via .github/workflows/ci.yml.

This workflow chains Astro’s build validation together with Lychee and Vale, creating a unified barrier against bad code and bad copy.

name: Docs CI & Quality Gates

on:
  pull_request:
    branches: [ main ]
  push:
    branches: [ main ]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
                - name: Checkout Repository
        uses: actions/checkout@v4

                - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: 'npm'

                - name: Install Dependencies
        run: npm ci

                - name: 1. Build & Zod Validation
        run: npm run build

                - name: 2. Link Checker (Lychee)
        uses: lycheeverse/lychee-action@v1.9.0
        with:
          args: --exclude-loopback --no-progress './**/*.md' './**/*.mdx'

                - name: 3. Prose Linting (Vale)
        uses: errata-ai/vale-action@reviewdog
        with:
          files: 'src/content/docs'
          reporter: github-pr-check

Why Automated Guardrails Matter

Implementing these pipelines transforms documentation maintenance from a reactive chore into a proactive system:

Eliminating Editorial Fatigue: Writers don’t need to manually proofread for passive voice or style compliance; Vale handles it objectively.
Zero Dead Links: Technical manuals lose credibility the moment a link fails. Lychee guarantees that every reference remains functional.
Confidence in Merges: Because the CI build acts as a strict gatekeeper, broken MDX tags or invalid frontmatter schemas can never accidentally make it into production.