Skip to content

GitHub Pages Setup

This document describes how the BookingZone platform documentation is published via GitHub Pages from this repository.

Overview

Setting Value
Site URL (current) https://aerospace-apps.github.io/bz-platform-context
Site URL (future) https://docs.prod.bookingzone.com (after DNS configured)
Source GitHub Actions (not branch-based)
Visibility Private (org members only)
Static Site Generator MkDocs with Material theme

How It Works

  1. Source of truth: All documentation lives in this repo as Markdown files.
  2. Build: The deploy-pages.yml workflow runs MkDocs to generate a static site.
  3. Deploy: The workflow uploads the built site to the github-pages environment.
  4. Custom domain: Not enabled yet — requires DNS setup first (see below).

Files Involved

File Purpose
mkdocs.yml MkDocs configuration: theme, plugins, navigation
site-src/index.md Site home page
.github/workflows/deploy-pages.yml Build and deploy workflow
.gitignore Excludes site/ (build output) from version control

Workflow Triggers

The deploy-pages.yml workflow runs on:

  • Push to main: Automatic deployment on merge
  • Manual dispatch: Run anytime via Actions → "Deploy to GitHub Pages" → Run workflow

Admin Setup (One-Time)

After merging, Anil (or a repo admin) must complete these steps in the GitHub UI:

1. Enable GitHub Pages

  1. Go to Settings → Pages in this repository.
  2. Under Build and deployment, set Source to GitHub Actions.
  3. Click Save.

2. Set Visibility to Private

  1. On the same Settings → Pages page, find Visibility.
  2. Select Private (requires GitHub Team plan; org already has this).
  3. Click Save.

Private visibility means only authenticated org members can access the site. The repo does not need to be public.

At this point, the site is live at: https://aerospace-apps.github.io/bz-platform-context

Custom Domain Setup (Later — After DNS Is Ready)

Important: Do NOT configure the custom domain in GitHub Pages until DNS is set up. Adding a custom domain without DNS causes the github.io URL to 404.

Step 1: Configure DNS First

Add this CNAME record to your DNS provider:

Type Name Value
CNAME docs.prod aerospace-apps.github.io

Wait for DNS propagation (verify with dig docs.prod.bookingzone.com or similar).

Step 2: Add CNAME File to Repo

Once DNS is working, add the CNAME file:

echo "docs.prod.bookingzone.com" > site-src/CNAME
git add site-src/CNAME
git commit -m "feat: enable custom domain for GitHub Pages"
git push

Step 3: Configure Custom Domain in GitHub

  1. On Settings → Pages, under Custom domain, enter: 
    docs.prod.bookingzone.com
  2. Click Save.
  3. GitHub will verify the domain (already verified at org level).

Step 4: Enforce HTTPS

  1. Once the custom domain shows "verified", check Enforce HTTPS.
  2. GitHub provisions a TLS certificate automatically.

Step 5: Update mkdocs.yml

Update site_url in mkdocs.yml:

site_url: https://docs.prod.bookingzone.com

The domain docs.prod.bookingzone.com is already verified at the org level in Organization Settings → Pages → Verified domains.

Local Development

To preview the site locally:

# Install dependencies
pip install mkdocs-material pymdown-extensions

# Serve with live reload
mkdocs serve

# Build static site
mkdocs build

The site will be available at http://127.0.0.1:8000.

Troubleshooting

Build fails with "file not found"

  • Check that all paths in mkdocs.yml nav match actual file locations.
  • Run mkdocs build --strict locally to catch issues.

Custom domain not working

  • Verify the CNAME DNS record points to aerospace-apps.github.io.
  • Check Settings → Pages shows the domain as verified.
  • Wait for DNS propagation (up to 24 hours, usually much faster).

Site not updating after merge

  • Check the Actions tab for workflow failures.
  • Ensure the github-pages environment exists and has correct permissions.

Content Authoring

All content lives in the existing repo structure:

  • adrs/ — Architecture Decision Records
  • constitution/ — System constitution
  • docs/ — Process documentation
  • glossary/ — Domain terminology
  • specs/ — Cross-cutting feature specs

Edit Markdown files directly. MkDocs handles YAML frontmatter gracefully (strips it from rendered pages via the meta extension).

To add a new page to the navigation, edit the nav: section in mkdocs.yml.