Documentation Tools Project — Complete Guide

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

Apply everything learned in this module by building a complete documentation tool stack. This project guides you through selecting tools, setting up a pipeline, and deploying a documentation site with search and analytics.

What You'll Learn

You will build a complete documentation tool stack from scratch, applying your knowledge of SSGs, hosting, search, analytics, and linting.

Why It Matters

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

Real-World Use

This project mirrors the documentation stack used by DodaTech for the tutorials platform: Hugo, markdownlint, cspell, HTMLProofer, Netlify, Typesense, and Plausible.

flowchart LR
  A[Project Start] --> B[Select SSG]
  B --> C[Configure Linting]
  C --> D[Set Up CI/CD]
  D --> E[Add Search]
  E --> F[Add Analytics]
  F --> G[Deploy]
  G --> H[Monitor and Improve]
  A:::current
  classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px

Project Requirements

Your documentation tool stack must include:

1. A static site generator (Hugo, MkDocs, or 11ty).
2. A linting configuration (markdownlint).
3. A spell check configuration (cspell).
4. A link checking configuration (HTMLProofer).
5. A CI/CD pipeline (GitHub Actions).
6. A hosting platform (Netlify, Vercel, or GitHub Pages).
7. Search integration (Lunr, Typesense, or Algolia).
8. Analytics integration (Plausible or Fathom).
9. At least 5 documentation pages with proper frontmatter.

Step 1: Select and Configure Your SSG

# Using Hugo
hugo new site docs-stack-project --format yaml
cd docs-stack-project
git init
git submodule add https://github.com/imfing/hextra.git themes/hextra

# Configure hugo.yaml with search and analytics
cat >> hugo.yaml << 'EOF'
theme: hextra
params:
  description: "Documentation stack project"
  plausible:
    domain: docs-stack-project.netlify.app
    src: https://plausible.io/js/script.js
EOF

Step 2: Configure Quality Tools

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

Save as .markdownlint.json.

# Create cspell config
cat > cspell.json << 'EOF'
{
  "version": "0.2",
  "language": "en-US",
  "words": ["DodaTech", "DodaZIP", "configurable"],
  "ignorePaths": ["node_modules", "public"]
}
EOF

Step 3: Create CI/CD Pipeline

# .github/workflows/ci.yml
name: Documentation CI
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: peaceiris/actions-hugo@v2
      - name: Lint
        run: npx markdownlint-cli2 content/
      - name: Spell check
        run: npx cspell "content/**/*.md"
      - name: Build
        run: hugo --gc --minify
      - name: Link check
        run: |
          npm install -g htmlproofer
          htmlproofer public/ --disable-external

Step 4: Deploy

Connect the Repository to Netlify or set up 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

Step 5: Add Analytics

Add the analytics script and verify data appears in the dashboard.

Deliverables

• Repository URL with complete tool stack.
• 5 documentation pages with proper frontmatter.
• CI pipeline that passes all checks.
• Live documentation site URL.
• Analytics dashboard with data.
• README.md explaining the stack and how to contribute.

Common Mistakes

1. Choosing Too Many Tools

Start with the minimum stack and add tools as needed. A stack with 10 tools creates 10 potential failure points.

2. Not Testing the Pipeline Locally

Do not commit a CI pipeline without running the same steps locally first.

3. Forgetting Analytics Configuration

Add analytics from the start. Adding analytics later requires changes to every page.

4. No Search

Documentation without search is frustrating. Implement search even if it is client-side Lunr.

5. No README

Contributors need to understand the stack and how to work with it. Document all tools in the README.

FAQ

What's Next

Congratulations on completing the Documentation Tools module. Explore the Developer Portal Guide to learn how to build comprehensive developer portals for APIs and SDKs.