CI/CD Automation and Content Workflow

CI/CD Automation and Content Workflow

Overview

Automating your documentation workflow ensures consistent quality, reduces manual errors, and enables rapid iteration. This section covers how to set up CI/CD pipelines, content migration scripts, and team collaboration workflows.

Q&A

Q: How do I automate builds with GitHub Actions?

A: Create a workflow file .github/workflows/deploy.yml:

name: Deploy Documentation
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
      - run: npm ci
      - run: npm run build
      - uses: actions/upload-artifact@v4
        with:
          name: dist
          path: dist/

  deploy:
    if: github.ref == 'refs/heads/main'
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: dist
          path: dist/
      # Deploy to your hosting platform

This workflow:

1. Builds on every push and pull request (catch errors early)
2. Deploys only when pushing to main
3. Caches npm dependencies for faster builds

Q: What is a content migration script and why do I need one?

A: A content migration script transforms your source content into the format expected by your documentation framework. This is especially useful when:

• Separating source from output: Keep raw content in source/ and auto-generate src/content/docs/
• Adding frontmatter: Automatically generate title, description, and other metadata
• Numbering and ordering: Use numbered directories in source but clean slugs in output
• Multilingual sync: Detect missing translations and generate placeholder pages

Example package.json hooks to run migration before build:

{
  "scripts": {
    "predev": "node scripts/migrate-content.mjs",
    "prebuild": "node scripts/migrate-content.mjs",
    "dev": "astro dev",
    "build": "astro build"
  }
}

The predev and prebuild hooks ensure content is always synchronized before Astro processes it.

Q: How do I set up a review workflow for documentation changes?

A: Use GitHub Pull Requests with branch protection:

1. Create a main branch with protection rules:

   • Require pull request reviews before merging
   • Require status checks (build must pass)

2. Workflow for content changes:

   Writer creates branch → Edits Markdown → Opens PR
   → CI builds preview → Reviewer approves → Merge to main → Auto-deploy

3. Preview deployments: Most hosting platforms (Vercel, Netlify) automatically create preview URLs for pull requests, so reviewers can see changes before merge.

Q: How do I handle versioning for documentation?

A: There are three common approaches:

Approach	Description	Best For
Single version	Always show latest docs	Simple products, fast-moving teams
Branch-based	Each version is a Git branch	Software with release versions
Tag-based	Use Starlight’s versioning plugin	Complex multi-version docs

For most technical documentation, a single-version approach (always latest) is sufficient. Add version information in the content itself when needed:

> [!NOTE]
> This guide applies to firmware v2.0 and later.
> For v1.x, see the [legacy documentation](/v1/guides/).

Q: How do I track documentation quality over time?

A: Implement automated quality checks:

1. Link checking: Use a tool like markdown-link-check in CI:

   npx markdown-link-check -c .linkcheck.json 'source/**/*.md'

2. Spelling and grammar: Use cspell or vale for automated proofreading

3. Build verification: Ensure the site builds without errors (already covered by CI)

4. Coverage metrics: Track how many pages have been translated, how many have descriptions, etc.

A simple CI check combining these:

- name: Check links
  run: npx markdown-link-check 'source/**/*.md'
- name: Check spelling
  run: npx cspell 'source/**/*.md'
- name: Build site
  run: npm run build

Building a commercial IoT product?

We provide ESP32 ODM design-to-manufacturing services. From prototype to production — the team behind this tutorial can build it with you.

Talk to us →