ivan-magda/claude-superpowers/swift-docc-github-pages

Claude Code and agent skill by ivan-magda/claude-superpowers

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

Use when setting up DocC documentation for a Swift package, deploying to GitHub Pages, or encountering "no such module 'UIKit'" during doc generation

Install

npx vskill@latest install ivan-magda/claude-superpowers/swift-docc-github-pages

SKILL.md

The same SKILL.md was published earlier as majiayu000/claude-skill-registry/swift-docc-github-pages.

Swift DocC to GitHub Pages

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

Which Build Method?

dot
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

ItemValue
Target nameFrom Package.swift: .target(name: "MyLib")
URL formathttps://USER.github.io/REPO/documentation/targetnamelowercase/
Enable PagesSettings → 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):

yaml
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

Cross-platform: Add dependency to Package.swift, replace Build Documentation step:

swift
dependencies: [
    .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0")
],
yaml
- name: Build Documentation
  run: |
    swift package --allow-writing-to-directory ./docs \
      generate-documentation --target TARGET_NAME \
      --disable-indexing \
      --transform-for-static-hosting \
      --hosting-base-path REPO_NAME \
      --output-path ./docs

Local Testing

bash
# iOS-only
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
 
# Cross-platform
swift package --allow-writing-to-directory ./docs \
  generate-documentation --target TARGET_NAME \
  --transform-for-static-hosting --hosting-base-path REPO_NAME --output-path ./docs

Common Mistakes

ErrorFix
"no such module 'UIKit'"iOS-only package: use xcodebuild docbuild
404 at root URLAdd redirect index.html step
Empty documentationEnsure types are public
Wrong URL caseTarget in URL is always lowercase
Pages not deployingEnable GitHub Actions as Pages source

Optional

Custom docs: Add Sources/TARGET_NAME/Documentation.docc/ with landing page and articles.

Swift Package Index: Add .spi.yml for automatic hosting:

yaml
version: 1
builder:
  configs:
    - documentation_targets: [TARGET_NAME]

Security

  • Security scanPassed, 90 of 100Pattern checks on the skill's files.
  • Model reviewPassed

See the full security report

Quality evaluation

  • Task evaluationNot runNo evaluation yet. Run one in Skill Studio.

See evaluation results

Source

Popularity

7-day trend score
0

Not refreshed yet.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

  • Claude Code
  • Cursor
  • GitHub Copilot
  • Windsurf
  • Codex
  • Gemini CLI
  • Cline
  • Amp
  • Roo Code
  • Goose
  • Continue
  • Kilo Code
  • Junie
  • Trae
  • OpenHands
  • Qwen Code
  • AI Agent
  • Tabnine Chat
  • Sourcegraph Cody
  • Amazon Q
  • Firebase Genkit
  • Sweep
  • Devin
  • Phind
  • Mentat
  • Claude Desktop
  • Aider
  • GPT Pilot
  • Plandex
  • bolt.new
  • v0
  • Replit Agent
  • Anse
  • TypingMind
  • BetterChatGPT
  • LibreChat
  • Warp AI
  • Pieces
  • Fig AI
Embed badge
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/ivan-magda/claude-superpowers/swift-docc-github-pages/badge)](https://verified-skill.com/skills/ivan-magda/claude-superpowers/swift-docc-github-pages)

Something wrong with this skill or its page? Tell us.