VersionedDocC: Versioned Swift-DocC websites, API diffs, and reusable release caches

Community Showcase
1

Hi everyone,

I've open sourced VersionedDocC, a tool for publishing and maintaining versioned Swift-DocC websites:

VersionedDocC is an orchestration layer around the existing Swift toolchain and DocC. It does not fork Swift-DocC or Swift-DocC Render.

It currently supports:

  • Documentation for a development branch and multiple releases
  • Stable versioned URLs such as /<project>/<version>/documentation/...
  • Release/main switching directly from the DocC header
  • API change pages generated from public symbol graphs
  • Multi-platform documentation assembled from platform-specific symbol graphs
  • Redirects from legacy, unversioned documentation URLs
  • Automatic selection of the latest patch from each release series
  • Immutable per-version caches, including OCI artifacts hosted on registries such as GHCR
  • SwiftPM, GitHub Actions, and GitHub Pages integration

The cache is designed so that publishing a new release does not require rebuilding every historical version. Previously generated release documentation can be restored independently, while only the new release and development documentation need to be built.

You can see live examples with ScreenShieldKit, Swift Book and Swift Syntax.

image
image4210Ă—2548 686 KB

The project is still evolving, and I'd appreciate feedback—particularly around the configuration format, API-diff presentation, caching model, and how this could integrate better with the broader Swift documentation ecosystem.

Getting started

VersionedDocC is configured through a .vdc.json file that describes the package target, DocC catalog, hosting path, release policy, platforms, and optional OCI cache.

In GitHub Actions, check out the full tag history and run the composite action:

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

- uses: OpenSwiftUIProject/VersionedDocC@0.0.8
  with:
    config: .vdc.json

It then discovers the configured releases, builds missing documentation, reuses cached historical releases, generates API comparisons, and assembles the versioned site.

For a complete integration with iOS/macOS documentation, GHCR caching, and GitHub Pages deployment, see the ScreenShieldKit adoption commit.

11 Likes