swift-docc-static

A tool and plugin to generate static HTML/CSS documentation for Swift packages that works without JavaScript.

Overview

swift-docc-static generates pure HTML/CSS documentation from Swift packages using the DocC infrastructure. The output can be viewed locally as file:// URLs or hosted on any static web server without requiring JavaScript for core functionality.

Aims / Features

• Pure HTML/CSS output - Documentation works without JavaScript enabled
• Full DocC support - API documentation, articles, and tutorials
• Light/Dark mode - Automatic theme switching based on system preferences
• Interactive tutorials - Display step-by-step tutorials with code examples and quizzes
• Cross-package linking - Relative links work with file:// URLs for testing
• Multi-target support - Document all targets in a package and create a common index page
• Optional search - Client-side search using Lunr.js (requires JavaScript)
• SPM plugin - Integrate documentation generation into your build process

Requirements

• Swift 6.2+

Installation

Using Homebrew

The easiest way to install on macOS or Linux:

brew tap mipalgu/tap
brew install swift-docc-static

Building from Source

git clone https://github.com/mipalgu/swift-docc-static.git
cd swift-docc-static
swift build -c release

The executable will be at .build/release/docc-static.

As a Package Dependency

The package provides a generate-static-documentation package command plugin that you can use directly in your own packages by simply adding the following to your Package.swift:

dependencies: [
    .package(url: "https://github.com/mipalgu/swift-docc-static.git", branch: "main"),
]

Usage

Generate Documentation

Generate documentation for a Swift package using the command-line tool:

docc-static generate --package-path /path/to/package --output ./docs

Options

Option	Description
-p, --package-path.	Path to the package directory (default: .).
-o, --output	Output directory (default: .build/documentation)
--scratch-path	Scratch path for Swift build operations
--symbol-graph-dir	Pre-generated symbol graph directory (skips build).
-t, --target	Specific targets to document (can be repeated)
-I, --include-all-dependencies	Include documentation for all dependencies
-i, --include-dependency	Include a specific dependency (can be repeated)
-x, --exclude-dependency	Exclude a specific dependency (can be repeated)
-e, --external-docs	External documentation URL (format: PackageName=URL)
--disable-search	Disable client-side search (enabled by default)
--footer	Custom HTML for the page footer
-v, --verbose	Enable verbose output

Examples

Generate documentation with verbose output:

docc-static generate -p ./MyPackage -o ./docs -v

Generate documentation for specific targets:

docc-static generate -t MyLibrary -t MyOtherLibrary -o ./docs

Include all dependencies except specific ones:

docc-static generate -I -x ExcludedPackage -o ./docs

Link to external documentation:

docc-static generate -e Foundation=https://developer.apple.com/documentation/foundation -o ./docs

Render from DocC Archive

Render static HTML from an existing .doccarchive:

docc-static render /path/to/MyPackage.doccarchive --output ./docs

Preview Documentation

Start a local preview server:

docc-static preview --output ./docs --port 8080

Then open http://localhost:8080 in your browser.

SPM Plugin

Use the Swift Package Manager plugin to generate documentation:

swift package generate-static-documentation

Or with options:

swift package --scratch-path /tmp/build generate-static-documentation

GitHub Pages Deployment

You can automatically deploy documentation to GitHub Pages using GitHub Actions. Add the following workflow to .github/workflows/documentation.yml:

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-15
    steps:
      - uses: actions/checkout@v4

      - uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: "26.1.1"

      - name: Build docc-static
        run: swift build -c release --product docc-static

      - name: Generate documentation
        run: |
          .build/release/docc-static generate \
            --package-path . \
            --output .build/documentation

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: .build/documentation

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

Then configure GitHub Pages in your repository settings:

1. Go to Settings → Pages
2. Under Build and deployment, select Source: GitHub Actions

Your documentation will be deployed to https://<username>.github.io/<repository>/.

Output Structure

docs/
├── index.html              # Main landing page
├── css/
│   └── main.css            # Stylesheet
├── js/                     # Optional JavaScript (search)
├── images/                 # Image assets
├── downloads/              # Downloadable files
├── videos/                 # Video assets
├── documentation/
│   └── mypackage/
│       ├── index.html      # Module overview
│       └── mytype/
│           └── index.html  # Type documentation
└── tutorials/
    ├── tutorials/
    │   └── index.html      # Tutorials overview
    └── mypackage/
        └── my-tutorial/
            └── index.html  # Tutorial page

Customisation

Custom Footer

Add custom HTML to the page footer:

docc-static generate --footer '<a href="https://example.com">My Company</a>'

Theming

The generated CSS uses CSS custom properties for theming. Override these in your own stylesheet to customise colours:

:root {
    --docc-bg: #ffffff;
    --docc-fg: #1d1d1f;
    --docc-accent: #0066cc;
    /* ... */
}

@media (prefers-color-scheme: dark) {
    :root {
        --docc-bg: #1d1d1f;
        --docc-fg: #f5f5f7;
        /* ... */
    }
}

Architecture

swift-docc-static leverages the existing DocC infrastructure:

• Uses SwiftDocC for symbol graph processing and content parsing
• Implements ConvertOutputConsumer to generate static HTML
• Renders RenderNode structures to pure HTML/CSS pages
• Supports all DocC content types: symbols, articles, and tutorials

Key Components

Component	Description
StaticDocumentationGenerator	Main orchestrator for documentation generation
StaticHTMLConsumer	Implements ConvertOutputConsumer protocol
HTMLPageBuilder	Builds HTML pages from RenderNode data
IndexPageBuilder	Creates the combined index page
SearchIndexBuilder	Generates Lunr.js search index

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

Licence

This project is available under the Apache License 2.0. See the LICENCE file for details.

Acknowledgements

• Swift DocC - Documentation compiler
• Swift DocC Plugin - Package documentation plugin
• Swift Argument Parser - CLI argument parsing
• Lunr.js - Client-side search (optional, requires JavaScript enabled in the browser)