What Is Docs-as-Code?

Docs-as-Code is a documentation methodology that applies software engineering discipline — version control, peer review, automated testing, continuous delivery — to how documentation is written, managed, and published. It is not a tool. It is a way of working.

The Core Idea

Software teams have spent decades building practices that make code reliable, traceable, and maintainable: every change is tracked in Git, reviewed by peers, tested automatically before it ships, and deployed with a repeatable process. Documentation teams have largely not had access to those same practices — until Docs-as-Code.

The insight is straightforward: documentation is a deliverable that belongs to the same codebase as the software it describes. When docs live in a Git repository, written in plain text formats like Markdown, they gain all the same properties as the code they document: full history, structured review, automated quality checks, and continuous deployment.

The Five Principles

1. 1
   Plain text source

   Documentation is written in a lightweight markup language — Markdown, MDX, or reStructuredText — not in proprietary formats. Plain text is readable by humans, diffable by tools, and not locked to any vendor.

2. 2
   Version controlled in Git

   Every change to every document is committed to a Git repository. The full history of who changed what, when, and why is permanently available. Branches enable parallel drafts without overwriting each other.

3. 3
   Reviewed like code

   Documentation changes go through pull requests. Subject-matter experts, editors, and engineers review the diff before anything merges. Review comments are visible, tracked, and resolved — creating a transparent editorial process.

4. 4
   Tested before publishing

   A CI pipeline runs automatically on every change. It checks for broken links, style guide violations, missing frontmatter, schema errors in OpenAPI specs, and any other quality rule the team defines. The build fails if standards are not met.

5. 5
   Deployed continuously

   When a change merges, the documentation site rebuilds and deploys automatically. The published site is always in sync with the repository. There is no manual publish step, no FTP uploads, no stale cached versions.

Traditional Docs vs Docs-as-Code

Area	Traditional Documentation	Docs-as-Code
Source format	Word, PDF, wiki markup	Markdown / MDX / OpenAPI
Version control	File naming (v2_FINAL.docx)	Git: full history, branches, tags
Review process	Email chains, tracked changes	Pull requests with inline comments
Quality checks	Manual proofreading	Automated lint, link checks, CI
Publishing	Manual export and upload	Automatic on merge
Audit trail	None or fragmented	Complete: every commit is signed
Multi-format output	Maintain separate files per format	One source → HTML, PDF, JSON, search index
Collaboration	One person edits at a time	Parallel branches, no conflicts until merge

The Toolchain

Docs-as-Code relies on a composable toolchain. You choose the tools that fit your stack — the methodology works with any combination.

Stage	Tools
Writing	VS Code, any text editor, or this platform's Live Editor
Version control	Git, GitHub, GitLab, Bitbucket
Build	MkDocs, Sphinx, Hugo, Docusaurus, Eleventy
Linting	Vale (style), markdownlint (structure), lychee (links)
CI/CD	GitHub Actions, GitLab CI, CircleCI, Jenkins
Hosting	GitHub Pages, Netlify, Vercel, AWS S3 + CloudFront

Quick Start Guide

This guide walks you through setting up a Docs-as-Code pipeline from scratch — from creating your repository to seeing your documentation go live on GitHub Pages. Estimated time: 15 minutes.

Prerequisites

Tool	Version	Purpose
git	2.x+	Version control for your docs source
python	3.10+	Required by MkDocs build engine
pip	latest	Installs MkDocs and plugins
GitHub account	—	Repository hosting and GitHub Pages deployment
Vale CLI	3.x+	Style linting (optional for quick start)

Setup Steps

1. 1
   Create and clone your repository

   Create a new public repository on GitHub, then clone it locally. This is where all your documentation source files will live.

git clone https://github.com/your-username/your-docs-repo.git
cd your-docs-repo

2. 2
   Install MkDocs and the Material theme

   MkDocs is the build engine. The Material theme provides a professional documentation portal layout out of the box.

pip install mkdocs mkdocs-material

3. 3
   Initialize the project structure

   Run mkdocs new . to scaffold the config file and docs/ directory. Your first document is created automatically.

mkdocs new .

# Output structure:
your-docs-repo/
├── mkdocs.yml          # site configuration
└── docs/
    └── index.md        # your first page

4. 4
   Configure your site

   Edit mkdocs.yml to set your site name, theme, and navigation. This is the single configuration file that controls the entire build.

site_name: My Documentation
site_url: https://your-username.github.io/your-docs-repo/
theme:
  name: material
  palette:
    scheme: slate
    primary: amber
nav:
  - Home: index.md
  - Getting Started: getting-started.md

5. 5
   Preview locally, commit, and deploy

   Run the local server to preview your site, then commit and push. GitHub Actions will build and deploy to GitHub Pages automatically.

# Preview locally on http://127.0.0.1:8000
mkdocs serve

# Commit and push
git add .
git commit -m "docs: initialize documentation site"
git push origin main

# Deploy to GitHub Pages manually (or via Actions)
mkdocs gh-deploy

The Docs Pipeline

The documentation pipeline is the automated workflow that takes a Markdown source file from a writer's editor to a published, validated, multi-format documentation site. It has five stages. Each stage is a quality gate — if a stage fails, the change does not proceed.

Stage 1: Write

Authors write documentation in Markdown (or MDX for React-based portals, or YAML/JSON for OpenAPI specs). The source format is chosen for portability: it can be read by any text editor, diffed by any version control tool, and compiled by any documentation build engine.

Good documentation source files follow a consistent structure: a frontmatter block (title, description, last reviewed date), then the content using headings, paragraphs, code blocks, and tables. The platform's Live Editor provides a split-pane environment to write and preview simultaneously.

---
title: Authentication
description: How to authenticate API requests using Bearer tokens
last_reviewed: 2026-02-01
---

# Authentication

All API requests must include a valid Bearer token in the `Authorization` header...

Stage 2: Commit & Review

Once the author is satisfied with a draft, they commit the change to a feature branch in Git and open a pull request. The pull request is the review interface: it shows exactly what changed (a readable diff of Markdown), allows inline comments on specific lines, and tracks when comments are resolved.

This stage enforces that no documentation reaches readers without being seen by at least one other person — whether a subject-matter expert, a peer writer, or an engineer who built the feature. The review history becomes a permanent record of editorial decisions.

Stage 3: Build

When the pull request is opened, the CI pipeline triggers a build. The build engine (MkDocs, Sphinx, or Hugo depending on configuration) compiles all Markdown source files into the configured output formats. A successful build confirms that the site structure is valid and all referenced files exist.

Stage 4: Validate

Validation runs in parallel with the build. The style linter (Vale) checks every changed file against the configured rule set. The link checker scans all internal and external links. Schema validators check OpenAPI specs. If any check fails, the CI run is marked failed and the pull request cannot merge until the issue is resolved.

Stage 5: Publish

When the pull request merges, the build and deploy workflow runs against the main branch. The compiled HTML site, PDF export, OpenAPI JSON, and search index are uploaded to the configured hosting target. The live site updates within minutes of the merge, with no manual intervention required.

Version Control for Documentation

Storing documentation in Git gives every team member a complete, auditable history of every change ever made. This page explains the branching strategy, commit conventions, and pull request process used in this platform.

Branching Strategy

Branch	Purpose	Merge target
main	Always-publishable source of truth. Protected: no direct commits.	—
docs/feature-name	New content or significant updates to existing content	main
docs/fix-*	Typo fixes, broken link repairs, minor corrections	main
release/vX.Y	Versioned documentation snapshot for a product release	main

Commit Conventions

Consistent commit messages make the Git log readable and enable automated changelog generation. This platform follows a documentation-specific adaptation of Conventional Commits:

docs(scope): short description of the change

# Examples:
docs(api): add rate limiting section to authentication page
docs(getting-started): fix broken link to quickstart guide
docs(compliance): update GDPR data residency table for EU region
fix(linting): resolve Vale rule violation in webhook reference
chore(config): update mkdocs.yml nav structure for v1.1

Pull Request Process

1. Author opens a PR from their feature branch against main
2. CI runs automatically: style lint, link check, build
3. At least one reviewer approves the content changes
4. All CI checks pass and review comments are resolved
5. Author or reviewer merges. Deployment runs automatically

CI/CD Integration

GitHub Actions powers the build, validate, and deploy stages of the pipeline. Every push to a pull request branch triggers validation. Every merge to main triggers a full build and deployment.

GitHub Actions Workflow

The following workflow file covers the full pipeline — linting, building, and deploying to GitHub Pages.

name: Docs CI/CD

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

jobs:
  lint-and-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 mkdocs mkdocs-material

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

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

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

Build Triggers

Event	Jobs run	Deploys?
Push to PR branch	Lint, build (strict mode)	No
Merge to main	Lint, build, deploy	Yes → GitHub Pages
Manual trigger	Full pipeline	Yes

Style Linting with Vale

Vale is a syntax-aware prose linter that enforces your documentation style guide automatically. It runs in CI on every pull request, catching inconsistencies before they reach readers — passive voice, banned terms, incorrect product names, and readability issues.

Configuration

StylesPath = .vale/styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, Google, DaC
DaC.PassiveVoice = warning
DaC.Terminology = error
Google.Headings = suggestion

Rule Categories

Level	Behavior	Example rules
error	Fails the CI build: must fix before merge	Wrong product name, banned term, broken heading hierarchy
warning	Reported in CI: should fix, does not block	Passive voice, "simply" / "just", future tense for features
suggestion	Advisory: fix when practical	Sentence length, heading capitalization, Oxford comma

Common Violations & Fixes

# ✗ Before
The request is authenticated by the server using a Bearer token.

# ✓ After
The server authenticates the request using a Bearer token.

# ✗ Before — "whitelist" is a banned term
Add your domain to the whitelist.

# ✓ After
Add your domain to the allowlist.

Multi-Format Output

A single Markdown source compiles into multiple output formats simultaneously. You write once, and the build pipeline produces an HTML documentation site, a PDF manual, an OpenAPI JSON specification, and a search index — all from the same source files.

Output Formats

Format	Use case	Tool
HTML site	Primary web documentation portal, hosted on GitHub Pages or Netlify	MkDocs / Material theme
PDF manual	Offline distribution, print, enterprise delivery	WeasyPrint or mkdocs-with-pdf
OpenAPI JSON	Machine-readable API spec for Postman, Swagger UI, SDK generation	Inline YAML → JSON conversion
Search index	Client-side full-text search, feeds the built-in portal search	MkDocs search plugin

Configuring Output Targets

plugins:
  - search
  - with-pdf:
      author: Sulagna Sasmal
      cover_title: Platform Documentation
      output_path: pdf/platform-docs.pdf
  - tags

Dashboard

The Dashboard is the command center for your documentation project. It gives an at-a-glance view of build health, content coverage, contributor activity, and recent pipeline runs.

Key Metrics

Metric	What it tells you
Build Status	Pass / fail of the last CI run, with link to logs
Content Coverage	Percentage of API endpoints, features, or topics with documentation
Lint Score	Number of open style warnings and errors across all files
Active Contributors	Authors with commits in the last 30 days
Last Published	Timestamp of the most recent successful deploy

Live Editor

The Live Editor is a split-pane Markdown authoring environment with real-time HTML preview and inline Vale linting. Authors can write, preview, and fix style issues without leaving the browser.

Features

• Split-pane view: Markdown source on the left, rendered HTML preview on the right, updated on every keystroke
• Frontmatter validation: highlights missing or malformed frontmatter fields before saving
• Inline lint markers: Vale violations are underlined in the editor with hover explanations
• Keyboard shortcuts: standard editor shortcuts for bold, italic, code, links, and headings
• Export: download the current file as .md or copy the rendered HTML

Content Map

The Content Map is a visual representation of your entire documentation structure — every page, its position in the hierarchy, its status, and its relationships to other pages.

What It Shows

• Doc tree: full navigation hierarchy rendered as an interactive graph
• Orphaned pages: pages that exist in the docs/ folder but are not referenced in the nav
• Broken cross-references: internal links that point to pages that do not exist
• Coverage gaps: sections of the nav that have placeholder stubs rather than full content
• Page metadata: last edited date, word count, lint status per page

Style Linter Module

The Style Linter module provides an interactive view of all active Vale rules, current violations across the codebase, and the ability to run a lint pass against any file on demand.

Panel Layout

• Rule browser: lists all active rules with their severity, description, and example violations
• Violations panel: all current lint issues grouped by file, filterable by severity
• Run on file: paste or select a file path and run Vale against it immediately
• Suppression manager: view and manage inline vale off / vale on suppressions across the codebase

For the full Vale configuration reference, see the Style Linting core concepts page.

Build Outputs

The Build Outputs module shows every artifact produced by the last successful pipeline run — with a preview, file size, and direct download or deploy link for each format.

Available Outputs

Output	Description	Typical size
HTML Site	Full static site ready for hosting. Includes search index and all assets.	2–15 MB
PDF Manual	Print-ready PDF with auto ToC, page numbers, and chapter breaks.	1–8 MB
OpenAPI JSON	Machine-readable API spec for Postman, Swagger UI, and SDK generation.	50–500 KB
Search Index	JSON index file for client-side full-text search.	100–800 KB

Configuration Module

The Configuration module provides a visual editor for the platform's docs-center.config.yml file — the single source of truth for site settings, navigation, theme, lint rules, and deploy targets.

Configuration Sections

• Site metadata: name, URL, description, author, copyright
• Navigation: page hierarchy, external links, nav sections
• Theme: color palette, logo, font, feature flags
• Lint rules: active Vale style sets, severity overrides, suppression list
• Build plugins: PDF export, search, tags, social cards
• Deploy targets: GitHub Pages, Netlify site ID, S3 bucket

For the full configuration schema reference, see the Config Schema reference page.

Configuration Schema

Complete reference for all fields in docs-center.config.yml. All fields are optional unless marked required.

Top-Level Fields

Field	Type	Description
site_name required	string	Display name of the documentation site
site_url	string	Canonical URL: used in sitemap and social meta tags
site_description	string	Short description for SEO and portal header
site_author	string	Author name for PDF cover and page meta
docs_dir	string	Directory containing Markdown source files. Default: docs/
site_dir	string	Directory for compiled output. Default: site/

Theme

theme:
  name: material
  palette:
    scheme: slate          # dark mode
    primary: amber
    accent: amber
  font:
    text: Inter
    code: JetBrains Mono
  features:
    - navigation.tabs
    - navigation.top
    - content.code.copy
    - search.highlight

Changelog

All notable changes to the Docs-as-Code Platform are documented here. This project follows Keep a Changelog and Semantic Versioning.

v1.0.0: 2026-02-28 Stable

Added

• Initial release of the Docs-as-Code Platform documentation portal
• Getting Started section: Introduction, What is Docs-as-Code, Quick Start Guide
• Core Concepts: Pipeline, Version Control, CI/CD Integration, Style Linting, Multi-Format Output
• Platform Module guides: Dashboard, Live Editor, Content Map, Style Linter, Build Outputs, Configuration
• Reference: Configuration Schema, Changelog
• GitHub Actions workflow example for full CI/CD pipeline
• Vale configuration examples with rule severity table
• Before/after examples for common lint violations
• Branching strategy and commit convention reference

Platform

• Dark amber theme consistent with VaultPay and CaseForge portfolio sites
• Fully interactive single-page navigation with dynamic table of contents
• Responsive layout: sidebar and TOC hide on smaller screens
• Hosted on GitHub Pages via SulagnaSasmal/docs-as-code-portal