CI/CD for Documentation — Complete Guide

CI/CD for documentation automates linting, building, testing, and deploying docs on every commit. Learn how to set up GitHub Actions, GitLab CI, and Netlify for documentation pipelines.

What You'll Learn

You will learn how to configure continuous integration and continuous deployment for documentation using major CI platforms, and how to choose the right approach for your project.

Why It Matters

Manual deployment is the single biggest source of documentation drift. CI/CD ensures every merge to main deploys automatically. It also catches errors in pull requests before they reach production.

Real-World Use

The DodaTech tutorials platform uses GitHub Actions for CI (linting, building, testing) and Netlify for CD (deploying to the global CDN). Every PR triggers a preview deploy, and every merge to main triggers a production deploy.

flowchart LR
  A[Developer Pushes Code] --> B[GitHub Actions Triggered]
  B --> C[Install Dependencies]
  C --> D[Run Linters]
  D --> E[Build Site]
  E --> F[Run Tests]
  F --> G{Pass?}
  G -->|Yes| H[Deploy to Production]
  G -->|No| I[Notify Developer]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

CI/CD with GitHub Actions

# .github/workflows/docs.yml
name: Docs CI/CD
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 0.134.0
      - name: Install linters
        run: npm install -g markdownlint-cli2
      - name: Lint
        run: markdownlint-cli2 content/
      - name: Build
        run: hugo --gc --minify
      - name: Deploy preview
        if: github.event_name == 'pull_request'
        uses: rossjrw/pr-preview-action@v1
        with:
          source-dir: public

CI/CD with GitLab CI

# .gitlab-ci.yml
image: node:20

before_script:
  - npm install -g markdownlint-cli2
  - wget https://github.com/gohugoio/hugo/releases/download/v0.134.0/hugo_extended_0.134.0_Linux-64bit.tar.gz
  - tar -xzf hugo_extended_0.134.0_Linux-64bit.tar.gz
  - mv hugo /usr/local/bin/

pages:
  script:
    - markdownlint-cli2 content/
    - hugo --gc --minify --baseURL $CI_PAGES_URL
  artifacts:
    paths:
      - public
  only:
    - main

CI/CD with Netlify

Netlify automatically detects Hugo, Docusaurus, and MkDocs projects. Add a netlify.toml for custom configuration:

# netlify.toml
[build]
  command = "hugo --gc --minify"
  publish = "public"

[build.environment]
  HUGO_VERSION = "0.134.0"

[context.deploy-preview]
  command = "hugo --gc --minify --buildDrafts"

Connected to a Git Repository, Netlify automatically deploys every push and creates preview deploys for every PR.

Branch-Based Deployments

Preview Deployments

Preview deployments create a temporary URL for each Pull Request. Reviewers can see the rendered documentation before approving the PR.

- name: Deploy PR preview
  uses: amondnet/vercel-action@v20
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    vercel-org-id: ${{ secrets.ORG_ID }}
    vercel-project-id: ${{ secrets.PROJECT_ID }}
    working-directory: ./

Common Mistakes

1. No CI on Pull Requests

Running CI only on main means errors reach production before anyone notices. Always run CI on pull requests too.

2. Hardcoding Secrets in the Repository

API tokens and deployment keys should be stored in CI secrets, not in the codebase. A leaked token compromises the deployment pipeline.

3. Deploying Without Building

Some CI configurations deploy the source files instead of the build output. Ensure the build command runs before the deploy step.

4. Ignoring PR Preview Deployments

Without preview deploys, reviewers must imagine how the formatted docs will look. Preview URLs remove this guesswork.

5. Not Caching Dependencies

Installing Hugo, npm packages, or Python tools from scratch on every build is slow. Cache dependencies between runs.

Practice Questions

1. What is the difference between CI and CD?

CI (Continuous Integration) runs automated checks on every commit. CD (Continuous Deployment) automatically deploys passing changes to production.

2. Why should CI run on pull requests, not just on main?

Running CI on pull requests catches errors before they merge, preventing broken documentation from reaching production.

3. What is a preview deployment?

A temporary URL that shows how the documentation will look after a PR merges, allowing reviewers to see the rendered output.

4. Which CI platform integrates most easily with GitHub?

GitHub Actions, since it is built into GitHub and requires no separate account.

5. Challenge: Set up a GitHub Actions workflow for a documentation repository that lints with markdownlint, builds with Hugo, deploys to Netlify on main pushes, and creates preview deployments for PRs.

FAQ

Mini Project

Create a CI/CD pipeline for a documentation repository that runs markdownlint, builds with Hugo or MkDocs, deploys to a free hosting platform, and sends a notification to a Slack channel on failure.

What's Next

With CI/CD configured, learn about Linting Docs with Vale and markdownlint to enforce style and formatting rules automatically.