Skip to content

Automation and CI/CD

Continuous Integration and Continuous Deployment (CI/CD) automates documentation workflows. Automation ensures quality, speeds delivery, and reduces manual errors.

What to Automate

Build Process

  • Generate HTML from source
  • Optimize images
  • Build search index
  • Create PDF versions

Quality Checks

  • Lint Markdown formatting
  • Check prose style
  • Validate links
  • Spell check
  • Test code samples

Deployment

  • Deploy to hosting
  • Invalidate CDN cache
  • Update search indexes
  • Notify stakeholders

CI/CD Platforms

GitHub Actions

name: Deploy Documentation

on:
  push:
    branches: [main]
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - name: Install dependencies
        run: pip install -r requirements.txt

      - name: Build docs
        run: mkdocs build --strict

      - name: Deploy
        if: github.ref == 'refs/heads/main'
        run: mkdocs gh-deploy --force

GitLab CI

pages:
  stage: deploy
  script:
    - pip install mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public
  only:
    - main

Quality Automation

- name: Check links
  run: |
    npm install -g markdown-link-check
    find docs -name "*.md" | xargs -n1 markdown-link-check

Prose Linting

- name: Vale linting
  uses: errata-ai/vale-action@v2
  with:
    files: docs/

Spell Checking

- name: Spell check
  run: |
    npm install -g cspell
    cspell "docs/**/*.md"

Preview Deployments

Deploy previews for pull requests:

- name: Deploy preview
  if: github.event_name == 'pull_request'
  uses: actions/deploy-pages@v2
  with:
    preview: true

Best Practices

  1. Build on every PR: Catch issues before merge
  2. Run quality checks: Automated gates for quality
  3. Deploy automatically: Reduce manual steps
  4. Use caching: Speed up builds
  5. Fail fast: Stop on first error

Summary

Automation improves documentation quality and delivery:

  • Automate builds, tests, and deployment
  • Run quality checks on every change
  • Deploy previews for review
  • Reduce manual work and errors