Docs-as-Code Project — Complete Guide

In this tutorial, you will learn about Docs. We cover key concepts, practical examples, and best practices to help you master this topic.

Apply everything you learned in this module by creating a complete docs-as-code pipeline. This project guides you through setting up a documentation Repository, CI/CD, linting, and deployment.

What You'll Learn

You will build a complete docs-as-code pipeline from scratch, applying version control, static site generation, linting, testing, and automated deployment.

Why It Matters

A complete pipeline project solidifies your understanding of how all the pieces fit together. It also gives you a reusable template for future documentation projects.

Real-World Use

This project mirrors the setup used by DodaTech for the tutorials platform. The same approach is used to document Doda Browser, DodaZIP, and Durga Antivirus Pro.

flowchart LR
  A[Project Setup] --> B[Git Repository]
  B --> C[Hugo Site]
  C --> D[Content Structure]
  D --> E[Linting Config]
  E --> F[CI Pipeline]
  F --> G[Deploy]
  G --> H[Analytics]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Project Requirements

Your documentation pipeline must include:

1. A Git repository with a proper .gitignore.
2. A static site generator (Hugo, MkDocs, or Docusaurus).
3. At least three documentation pages with frontmatter.
4. A linting configuration (markdownlint).
5. A spell checking configuration (cspell).
6. A GitHub Actions workflow that runs linting and builds.
7. A deployment to a hosting platform (Netlify, GitHub Pages, Vercel).
8. A README.md that documents the pipeline.

Step 1: Initialize the Repository

mkdir docs-pipeline-project && cd docs-pipeline-project
git init
echo "node_modules/" > .gitignore
echo "public/" >> .gitignore
echo ".DS_Store" >> .gitignore
git add .gitignore
git commit -m "Initial commit with .gitignore"

Step 2: Set Up the Static Site Generator

# Using Hugo
hugo new site . --format yaml
git submodule add https://github.com/imfing/hextra.git themes/hextra
echo "theme: hextra" >> hugo.yaml
git add .
git commit -m "Add Hugo with Hextra theme"

Step 3: Create Documentation Content

hugo new content/getting-started/_index.md
hugo new content/getting-started/installation.md
hugo new content/guides/configuration.md
hugo new content/api/reference.md

Edit each page with proper frontmatter and content.

Step 4: Configure Linting

{
  "default": true,
  "MD013": false,
  "MD024": false,
  "MD033": false,
  "MD041": false
}

Save as .markdownlint.json and commit.

Step 5: Configure Spell Checking

{
  "version": "0.2",
  "language": "en-US",
  "words": ["DodaTech", "backend", "configurable"],
  "ignorePaths": ["node_modules", "public"]
}

Save as cspell.json and commit.

Step 6: Create the CI Workflow

# .github/workflows/ci.yml
name: Docs CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-hugo@v2
        with:
          hugo-version: 0.134.0
      - name: Install tools
        run: npm install -g markdownlint-cli2 cspell
      - name: Lint
        run: markdownlint-cli2 content/
      - name: Spell check
        run: cspell "content/**/*.md"
      - name: Build
        run: hugo --gc --minify

Step 7: Deploy

For GitHub Pages:

- name: Deploy to GitHub Pages
  uses: peaceiris/actions-gh-pages@v3
  if: github.ref == 'refs/heads/main'
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./public

For Netlify (connect repo through Netlify UI).

Step 8: Add Analytics

<script defer data-domain="your-site.netlify.app"
  src="https://plausible.io/js/script.js">
</script>

Deliverables

Submit or present:

• Repository URL with complete pipeline.
• Three documentation pages with proper frontmatter.
• CI workflow that passes all checks.
• Live documentation site URL.
• README.md explaining how to contribute.

Common Mistakes

1. Not Configuring .gitignore

Missing .gitignore leads to committed dependencies and build artifacts. Always include node_modules, public, and OS files.

2. Skipping the Docker or Local Test

Do not assume the CI will pass. Test the linting and build commands locally first.

3. No README

Contributors need to know how to clone, install, and build. Write a clear README.

4. Ignoring Mobile Responsiveness

Deploy the site and check that it renders correctly on mobile devices.

5. No Monitoring After Deployment

Set up analytics to verify the site is working and to track usage.

FAQ

What's Next

Congratulations on completing the Docs-as-Code module. Explore the Documentation Tools Comparison to evaluate different tools for your stack. Then learn about Developer Portal Guide.