PraisonAIUI/docs/getting-started/github-pages.md

Deploy to GitHub Pages

Ship your AIUI docs site to GitHub Pages with one workflow file.

Quick Start

1. Project Structure

my-project/
├── aiui.template.yaml    # Site configuration
├── docs/                 # Your markdown content
│   ├── index.md
│   └── guide.md
├── CNAME                 # Custom domain (optional)
└── .github/
    └── workflows/
        └── deploy.yml    # GitHub Actions workflow

2. Configuration

Create aiui.template.yaml:

schemaVersion: 1

site:
  title: "My Docs"
  description: "Documentation for my project"
  ui: "shadcn"
  theme:
    preset: "zinc"
    darkMode: true

content:
  docs:
    dir: "./docs"
    include:
      - "**/*.md"

templates:
  docs:
    layout: "ThreeColumnLayout"
    slots:
      header: { ref: "header_main" }
      left: { ref: "sidebar_docs" }
      main: { type: "DocContent" }
      footer: { ref: "footer_main" }

components:
  header_main:
    type: "Header"
    props:
      logoText: "My Docs"
  footer_main:
    type: "Footer"
    props:
      text: "© 2026"
  sidebar_docs:
    type: "DocsSidebar"
    props:
      source: "docs-nav"

routes:
  - match: "/docs/**"
    template: "docs"

3. GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy Docs

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

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

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install AIUI
        run: pip install aiui

      - name: Build
        run: |
          aiui build --output site --minify
          # Preserve custom domain (if using one)
          [ -f CNAME ] && cp CNAME site/CNAME

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v4
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./site

4. Enable GitHub Pages

1. Go to Settings → Pages in your GitHub repo
2. Set Source to Deploy from a branch
3. Set Branch to gh-pages / / (root)
4. Push to main — your site deploys automatically

Custom Domain

To use a custom domain (e.g., docs.example.com):

1. Create a CNAME file in your repo root:

   docs.example.com
   

2. Configure DNS — add a CNAME record pointing to <username>.github.io
3. The workflow above automatically copies CNAME into the build output

Migrating from MkDocs

Already using MkDocs? The migration is simple:

MkDocs	AIUI
mkdocs.yml	aiui.template.yaml
mkdocs build → ./site/	aiui build --output site → ./site/
mkdocs serve	aiui serve
pip install mkdocs-material	pip install aiui

Your existing docs/ folder works as-is — just swap the config and build command.

Migration Steps

1. Create aiui.template.yaml (see example above)
2. Replace mkdocs build with aiui build --output site --minify in your CI workflow
3. Remove mkdocs.yml (optional — keep for reference)
4. Push to main

Local Preview

Preview your site before deploying:

# Build and serve locally
aiui build
aiui serve

# Or use dev mode with hot reload
aiui dev

Build Output

aiui build --output site produces:

site/
├── index.html           # SPA entry point
├── assets/              # JS + CSS bundles
│   ├── index.js
│   └── index.css
├── ui-config.json       # Site configuration manifest
├── docs-nav.json        # Navigation tree
├── route-manifest.json  # Route definitions
└── docs/                # Markdown content (copied)
    ├── index.md
    └── ...

Everything is static — no server required. GitHub Pages serves it directly.