Skip to main content

ADR-007: GitHub Pages Documentation Deployment

Status​

Accepted

Context​

The project documentation needs to be:

  1. Publicly accessible: Developers can read without authentication
  2. Automatically deployed: Changes go live on merge to main
  3. Searchable: Full-text search across all docs
  4. Versioned: Can view docs for different versions

Options considered:

  • README only: Simple but doesn't scale
  • GitHub Wiki: Built-in but limited formatting
  • Docusaurus + GitHub Pages: Full-featured, free hosting
  • GitBook/ReadTheDocs: Third-party service, potential cost

Decision​

We will use Docusaurus deployed to GitHub Pages:

  1. Docusaurus: React-based static site generator
  2. GitHub Pages: Free hosting from the repository
  3. GitHub Actions: Automated build and deploy on push

Directory Structure​

Vertical-Template/
├── docs/                    # Markdown documentation source
│   ├── getting-started/
│   ├── architecture/
│   ├── configuration/
│   └── ...
├── docs-site/               # Docusaurus configuration
│   ├── docusaurus.config.ts
│   ├── sidebars.ts
│   └── src/                 # Custom pages/components
└── .github/workflows/
    └── deploy-docs.yml      # GitHub Actions workflow

Deployment Workflow​

# .github/workflows/deploy-docs.yml
name: Deploy Documentation
on:
  push:
    branches: [main]
    paths: ['docs/**', 'docs-site/**']

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
        working-directory: docs-site
      - run: npm run build
        working-directory: docs-site
      - uses: actions/deploy-pages@v4

URL Structure​

  • Production: https://enterpriseaigroup.github.io/Vertical-Template/
  • Docs: https://enterpriseaigroup.github.io/Vertical-Template/docs/

Consequences​

Positive​

  • Free hosting: GitHub Pages is included with repository
  • Auto-deploy: Changes live within minutes of merge
  • Full-featured: Search, dark mode, versioning available
  • MDX support: React components in markdown

Negative​

  • Build step: Documentation requires build process
  • Public only: All docs are publicly accessible
  • Single version: Versioning requires additional setup

Neutral​

  • Docusaurus learning: Team needs to learn configuration
  • Styling: Docusaurus theme can be customized