swift-docc-github-pages

Swift DocC to GitHub Pages

Automate Swift package documentation publishing to GitHub Pages via GitHub Actions.

Which Build Method?

digraph method_choice {
    "Check Package.swift platforms" [shape=box];
    "iOS only?" [shape=diamond];
    "Use xcodebuild docbuild" [shape=box, style=filled, fillcolor=lightblue];
    "Use swift-docc-plugin" [shape=box];

    "Check Package.swift platforms" -> "iOS only?";
    "iOS only?" -> "Use xcodebuild docbuild" [label=".iOS only"];
    "iOS only?" -> "Use swift-docc-plugin" [label="includes .macOS"];
}

Why? swift package generate-documentation builds for macOS. iOS-only packages fail with "no such module 'UIKit'".

Quick Reference

Item	Value
Target name	From Package.swift: .target(name: "MyLib")
URL format	https://USER.github.io/REPO/documentation/targetnamelowercase/
Enable Pages	Settings → Pages → Source → "GitHub Actions"

Workflow

Create .github/workflows/docc.yml. Replace TARGET_NAME, TARGET_NAME_LOWERCASE, REPO_NAME.

iOS-only (no Package.swift changes needed):

name: Documentation

on:
  push:
    branches: [main]
  workflow_dispatch:

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

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  build:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v6

      - name: Setup Xcode
        uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: latest-stable

      - name: Build Documentation
        run: |
          xcodebuild docbuild \
            -scheme TARGET_NAME \
            -destination "generic/platform=iOS Simulator" \
            -derivedDataPath .derivedData

          $(xcrun --find docc) process-archive transform-for-static-hosting \
            .derivedData/Build/Products/Debug-iphonesimulator/TARGET_NAME.doccarchive \
            --hosting-base-path REPO_NAME \
            --output-path ./docs

      - name: Add redirect
        run: |
          cat > ./docs/index.html << 'EOF'
          <!DOCTYPE html><html><head>
            <meta http-equiv="refresh" content="0; url=documentation/TARGET_NAME_LOWERCASE/">
          </head></html>
          EOF

      - uses: actions/upload-pages-artifact@v4
        with:
          path: ./docs

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - uses: actions/deploy-pages@v4
        id: deployment