Michael Uzukwu

Posted on Aug 8

A Beginner-Friendly Guide to Docs as Code & CI/CD Pipelines

#documentation #cicd #githubactions #opensource

In today's software world, documentation is no longer a side task—it’s a core part of the development lifecycle. If you've heard terms like “Docs as Code” and “CI/CD pipelines”, but they sound intimidating or too advanced, this guide is for you.

Whether you’re a technical writer, developer, or contributor to an open-source project, you'll learn how to automate documentation deployment using a static site generator and GitHub Actions. No complex DevOps background needed.

What Is “Docs as Code”?

Docs as Code is a modern approach that treats documentation just like source code. Instead of writing docs in Google Docs or Word, you write them in Markdown, version them in Git, and manage them in the same repository as the project.

This approach allows:

Team collaboration through version control (like Git)
Code reviews and pull requests for documentation
Automated building and deployment (CI/CD)
Reuse of developer tools for docs workflows

CI/CD Pipeline

CI/CD stands for Continuous Integration and Continuous Deployment. It means:

CI: Automatically checking your code or docs when you push changes (e.g., spellcheck, linting, tests).
CD: Automatically building and deploying your site to the web without manual steps.

In this article, we’ll use GitHub’s Actions feature to run our CI/CD pipeline whenever we push to the main branch.

Why This Guide Matters

While some static site generators (SSGs) like Astro Starlight or Next.js do offer native/auto-deployment especially on platforms like Vercel, Netlify, etc, others like MkDocs, Hugo, and Docusaurus don't—especially when using GitHub Pages for hosting.

To solve this gap, we’ll create our own automated workflow using:

MkDocs (a Python-based static site generator)
GitHub Actions (for automation)
GitHub Pages (for free hosting)

By the end, you’ll have a workflow where your documentation deploys automatically each time you push changes.

Benefits of This Setup

Zero cost: Everything uses free GitHub features.
Automation: No need to deploy manually.
Versioned and traceable: Every change is recorded in Git.
Lightweight: Minimal setup needed for personal or team docs.

Prerequisites

Before starting, you should have:

A GitHub account and repository set up
Basic knowledge of Markdown and Git
Python installed locally
MkDocs installed (pip install mkdocs mkdocs-material)

Project Recap: What We Deployed

For this demo, we built and deployed a simple Vue.js documentation site using MkDocs and hosted it at:
👉 demo site
It currently includes:

A custom homepage
Introduction page
Quick Start guide

Step-by-Step: Set Up CI/CD for MkDocs with GitHub Pages

Here’s how we set up the pipeline:

Understand the Flow When you push changes to your main branch, GitHub Actions will:
Detect the change (triggered by the on: push event in deploy.yml).

Checkout your repo code into the workflow environment.
Set up Python (since MkDocs is Python-based).
Install MkDocs and the Material theme.
Build the documentation into static HTML.
Deploy it to the gh-pages branch, which GitHub Pages serves as your live site.

Project Folder Structure Your folder should look like this:

vue.js-mkdocs-demo/
├── docs/
│   ├── index.md
│   ├── introduction.md
│   └── quick-start.md
├── mkdocs.yml
├── .github/
│   └── workflows/
│       └── deploy.yml

Create a deploy.yml Workflow File Inside .github/workflows/, create a file named deploy.yml and include your script similar to this:

name: Deploy MkDocs Site

on:
  push:
    branches:
      - main  # deploy when pushing to main

permissions:
  contents: write  # needed to push to gh-pages branch

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4

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

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install mkdocs mkdocs-material

      - name: Build and deploy
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: mkdocs gh-deploy --force --remote-name origin

Fig1: Code syntax showing the 'deploy.yml' file setup for the CI/CD Pipeline

This pipeline:

Runs when you push to the main branch
Installs Python and MkDocs
Builds your docs
Deploys them to GitHub Pages

Push and Watch the Pipeline Run Once you’ve created the file:

git add .github/workflows/deploy.yml
git commit -m "Add MkDocs deployment workflow"
git push origin main

Go to the Actions tab in your GitHub repo.
You should see the “Deploy MkDocs Site” workflow running.
Click into it to watch each step (checkout, setup, install, build, deploy).
All steps should turn green ✅ when successful.

Fig2: Set up Configurations for Github Pages

Fig4: Github Actions Flow Showing Successful deployment.

View Your Live Documentation Once the workflow finishes, your site will be live at:

https://<your-username>.github.io/<repo-name>/

Fig5: Live Site of deployed Vue.js docs built with Mkdocs

Wrapping Up

This guide proves that documentation automation isn’t just for large dev teams—it’s beginner-friendly and accessible. By using Docs as Code practices with GitHub Actions and MkDocs, you ensure your docs stay live, versioned, and up-to-date with zero manual deployment effort.

Treating docs like code saves time, builds consistency, and improves collaboration. If you're new to CI/CD or static site generators, this hands-on tutorial is a solid start.

[Live Site](https://mike-4-prog.github.io/vue.js-mkdocs-demo/)
[Github Repo](https://github.com/Mike-4-prog/vue.js-mkdocs-demo)