Shared Documentation Setup

All Gamma projects use a consistent documentation theme and configuration. This guide explains how to add documentation to your project.

Quick Start

1. Create your workflow

Add .github/workflows/docs.yml to your project:

name: Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
      - 'mkdocs-project.yml'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  docs:
    uses: go-gamma/go-gamma.github.io/.github/workflows/docs-deploy.yml@main
    with:
      site-name: "Your Project Name"
      site-url: "https://go-gamma.github.io/your-repo"
      repo-url: "https://github.com/go-gamma/your-repo"
      repo-name: "go-gamma/your-repo"

2. Add your docs

Create a docs/ directory with your markdown files:

docs/
├── index.md
├── getting-started.md
└── api/
    └── reference.md

3. Configure navigation

Create mkdocs.yml with your navigation:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API Reference: api/reference.md

4. Enable GitHub Pages

1. Go to Settings → Pages
2. Set Source to GitHub Actions

Push to main and your docs will deploy automatically.

---

Workflow Inputs

Input	Required	Default	Description
site-name	Yes	—	Documentation site title
site-url	No	''	Full deployment URL (e.g., https://go-gamma.github.io/dynorm)
site-description	No	''	Site description for SEO
repo-url	No	''	GitHub repository URL
repo-name	No	''	Repository name (e.g., go-gamma/dynorm)
python-version	No	'3.12'	Python version for build
extra-plugins	No	''	Additional pip packages (space-separated)
deploy	No	true	Whether to deploy to GitHub Pages
strict	No	true	Fail build on warnings

Full Example

name: Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'mkdocs.yml'
  pull_request:
    paths:
      - 'docs/**'
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  # Build only on PRs (no deploy)
  build:
    if: github.event_name == 'pull_request'
    uses: go-gamma/go-gamma.github.io/.github/workflows/docs-deploy.yml@main
    with:
      site-name: "dynorm"
      site-description: "Type-safe DynamoDB ORM for Go"
      repo-url: "https://github.com/go-gamma/dynorm"
      repo-name: "go-gamma/dynorm"
      deploy: false

  # Build and deploy on push to main
  deploy:
    if: github.event_name != 'pull_request'
    uses: go-gamma/go-gamma.github.io/.github/workflows/docs-deploy.yml@main
    with:
      site-name: "dynorm"
      site-url: "https://go-gamma.github.io/dynorm"
      site-description: "Type-safe DynamoDB ORM for Go"
      repo-url: "https://github.com/go-gamma/dynorm"
      repo-name: "go-gamma/dynorm"

---

Configuration Options

Option 1: Minimal (nav only)

Create mkdocs.yml with just navigation. Everything else comes from the shared base:

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - API: api/index.md

Option 2: Project overrides

Create mkdocs.yml with specific overrides. Your settings merge with the base:

site_name: My Project

nav:
  - Home: index.md
  - API: api/index.md

extra:
  version: "2.0.0"

theme:
  palette:
    - scheme: default
      primary: teal  # Override the default blue

Option 3: Full control

Create a complete mkdocs.yml. The shared styles and overrides are still applied:

site_name: My Project
site_url: https://go-gamma.github.io/my-project
repo_url: https://github.com/go-gamma/my-project
repo_name: go-gamma/my-project

nav:
  - Home: index.md
  - Guide:
      - Installation: guide/install.md
      - Usage: guide/usage.md
  - API: api/index.md

theme:
  name: material
  features:
    - navigation.instant
    - navigation.tabs
    - content.code.copy

---

Extra Plugins

Install additional MkDocs plugins:

jobs:
  docs:
    uses: go-gamma/go-gamma.github.io/.github/workflows/docs-deploy.yml@main
    with:
      site-name: "My Project"
      extra-plugins: "mkdocs-git-revision-date-localized-plugin mkdocs-awesome-pages-plugin"

Or add a requirements-docs.txt to your project — it will be installed automatically.

---

Customization

Custom Styles

Add project-specific styles in docs/stylesheets/extra.css:

/* Appended after shared Gamma styles */
:root {
  --md-primary-fg-color: #00897b;  /* Teal instead of blue */
}

Custom Templates

Create an overrides/ directory for template customization:

overrides/
├── main.html              # Extend base template
└── partials/
    └── header.html        # Override specific partials

See Material for MkDocs Customization.

---

What You Get

Projects using the shared workflow automatically receive:

Theme

• Blue color scheme with light/dark mode
• Inter font for text, JetBrains Mono for code
• Full-width layout
• Sticky navigation tabs

Features

• Instant navigation with prefetch
• Full-text search with suggestions
• Code blocks with copy button and line numbers
• Mermaid diagram support
• Admonitions, tabs, and task lists

Build

• Strict mode (fails on warnings)
• HTML/CSS/JS minification
• Privacy plugin for external assets
• Link validation

---

Local Development

# Install dependencies
pip install mkdocs-material mkdocs-minify-plugin

# Serve locally with auto-reload
mkdocs serve

# Build static site
mkdocs build --strict

Open http://127.0.0.1:8000 to preview.