realm · jadar · Jan 14, 2026
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,131 @@
+name: Deploy Documentation
+
+on:
+  # Runs on pushes to master
+  push:
+    branches:
+      - master
+  # Allows manual trigger from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: macos-15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Read SDK version
+        id: get-version
+        run: |
+          version="$(sed -n 's/^VERSION=\(.*\)$/\1/p' "${GITHUB_WORKSPACE}/dependencies.list")"
+          echo "VERSION=$version" >> $GITHUB_OUTPUT
+          echo "Building documentation for version: $version"
+
+      - name: Build Swift documentation
+        run: |
+          bundle exec sh build.sh docs swift
+
+      - name: Build Objective-C documentation
+        run: |
+          bundle exec sh build.sh docs objc
+
+      - name: Prepare documentation for deployment
+        run: |
+          mkdir -p _site
+          # Copy Swift docs
+          if [ -d "docs/swift_output" ]; then
+            cp -r docs/swift_output _site/swift
+          fi
+          # Copy Objective-C docs
+          if [ -d "docs/objc_output" ]; then
+            cp -r docs/objc_output _site/objc
+          fi
+          # Create an index page
+          cat > _site/index.html << 'EOF'
+          <!DOCTYPE html>
+          <html lang="en">
+          <head>
+            <meta charset="UTF-8">
+            <meta name="viewport" content="width=device-width, initial-scale=1.0">
+            <title>Realm Swift Documentation</title>
+            <style>
+              body {
+                font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+                max-width: 800px;
+                margin: 50px auto;
+                padding: 20px;
+                line-height: 1.6;
+              }
+              h1 {
+                color: #333;
+              }
+              .links {
+                margin-top: 30px;
+              }
+              .links a {
+                display: block;
+                margin: 15px 0;
+                padding: 15px;
+                background-color: #f6f8fa;
+                border-radius: 6px;
+                text-decoration: none;
+                color: #0366d6;
+                font-size: 18px;
+                transition: background-color 0.2s;
+              }
+              .links a:hover {
+                background-color: #e1e4e8;
+              }
+            </style>
+          </head>
+          <body>
+            <h1>Realm Swift Documentation</h1>
+            <p>Welcome to the Realm Swift API documentation.</p>
+            <div class="links">
+              <a href="swift/">Swift API Documentation →</a>
+              <a href="objc/">Objective-C API Documentation →</a>
+            </div>
+            <p style="margin-top: 40px; color: #666;">
+              For more information, visit the 
+              <a href="https://github.com/realm/realm-swift">realm-swift GitHub repository</a>.
+            </p>
+          </body>
+          </html>
+          EOF
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: '_site'
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/GITHUB_PAGES_SETUP.md b/docs/GITHUB_PAGES_SETUP.md
@@ -0,0 +1,101 @@
+# GitHub Pages Documentation Setup
+
+This repository is configured to automatically build and deploy documentation to GitHub Pages using GitHub Actions.
+
+## Setup Instructions
+
+To enable GitHub Pages for this repository, follow these steps:
+
+### 1. Enable GitHub Pages
+
+1. Go to your repository on GitHub
+2. Navigate to **Settings** → **Pages**
+3. Under **Source**, select **GitHub Actions** as the deployment source
+4. Save the changes
+
+### 2. Workflow Trigger
+
+The documentation will be automatically built and deployed when:
+- Code is pushed to the `master` branch
+- The workflow is manually triggered from the **Actions** tab
+
+### 3. Accessing the Documentation
+
+Once deployed, the documentation will be available at:
+```
+https://<username>.github.io/<repository-name>/
+```
+
+For the realm-swift repository, it will be:
+```
+https://realm.github.io/realm-swift/
+```
+
+The documentation includes:
+- **Swift API Documentation**: Available at `/swift/`
+- **Objective-C API Documentation**: Available at `/objc/`
+
+## Workflow Overview
+
+The GitHub Actions workflow (`.github/workflows/deploy-docs.yml`) performs the following steps:
+
+1. **Checkout**: Fetches the repository code
+2. **Setup Ruby**: Installs Ruby and dependencies from the Gemfile (including Jazzy)
+3. **Build Documentation**: 
+   - Builds Swift documentation using `bundle exec sh build.sh docs swift`
+   - Builds Objective-C documentation using `bundle exec sh build.sh docs objc`
+4. **Prepare Deployment**: Organizes documentation into a `_site` directory structure
+5. **Deploy**: Uploads and publishes the documentation to GitHub Pages
+
+## Local Development
+
+To build the documentation locally:
+
+```bash
+# Install dependencies
+bundle install
+
+# Build Swift documentation
+sh build.sh docs swift
+
+# Build Objective-C documentation  
+sh build.sh docs objc
+```
+
+The output will be in:
+- `docs/swift_output/` - Swift API documentation
+- `docs/objc_output/` - Objective-C API documentation
+
+## Requirements
+
+- **macOS runner**: Required for building the documentation (uses Xcode tools)
+- **Ruby**: Installed via `ruby/setup-ruby` action
+- **Jazzy**: Installed via Bundler from the Gemfile
+- **GitHub Pages permissions**: Configured in the workflow file
+
+## Customization
+
+To customize the documentation:
+
+- Edit `docs/custom_head.html` to modify the HTML head section
+- Modify the workflow file to change build behavior
+- Edit the index page generation in the workflow to customize the landing page
+
+## Troubleshooting
+
+If the deployment fails:
+
+1. Check the **Actions** tab for error logs
+2. Ensure GitHub Pages is enabled in repository settings
+3. Verify that the repository has the necessary permissions
+4. Check that all Ruby dependencies are properly specified in the Gemfile
+
+## Manual Deployment
+
+To manually trigger a documentation deployment:
+
+1. Go to the **Actions** tab in the repository
+2. Select the **Deploy Documentation** workflow
+3. Click **Run workflow**
+4. Select the branch (usually `master`)
+5. Click the green **Run workflow** button