Swift's New Documentation Site

Swift Website
,
1

The Swift project has new hosted documentation, now live.

The tl;dr:

To set expectations, this is a living site for Swift, not a finished, polished product. We wanted to get it out there for immediate use and keep improving it as we go forward. Our aim is better, accessible docs (reference, guides, and examples) for the Swift project and language.

Background

This is the next step in work that stretches back almost two years. It started with the Swift Information Architecture Project, followed by a proposal to build combined docs from that project. That resulted in the creation of the docs repository (swiftlang/docs) in February 2026.

Almost all the workgroups within Swift collaborated on this work, along with a lot of individuals who helped make great content available.

What's included

Here's what the new site brings together:

  • The Swift Programming Language with its introduction, language guide, and reference.
  • The reference API for the Swift standard library and testing.
  • Content sourced from across the repositories in swiftlang — written in markdown, built using DocC, and updated nightly from the relevant branches.

This includes documentation for the toolchain, language, and platform-specific details for using Swift. We're continuing to host documentation for libraries and Swift packages on the Swift Package Index.

What's not there yet

We expect a few readers will note that Foundation isn't yet included. We're actively working on open sourcing the reference API content and including it, akin to what we did with the Swift standard library.

Versioning

This also marks a step toward providing documentation and guides versioned to the Swift releases, and supporting versioned content going forward. The URL slug latest presents documentation built from the most recent release branch—right now that's release/6.4.x, since 6.4 hasn't shipped yet. We also have main, which presents the nightly development branch. In the near future we'll also have 6.4 as a URL slug referencing previously released documentation when we step forward beyond 6.4 as our current release. The old links still work, and redirects for this new structure are live now.

What's next

There's more work immediately upcoming on how these docs are built and presented. These docs are primarily (but not completely) built with some of the experimental work in DocC to make the content more accessible, including markdown output in the DocC archive and fuller HTML content to make the details available to crawlers and indexers.

Coming up, we want to add explicit canonical tags into the output, as well as add a version switcher so it's easier to move between the versions we host, rather than relying on readers to know a different URL exists.

We're continuing to work closely with the DocC team, feeding back the lessons and gaps we've found so far to help improve DocC and this documentation going forward.

Also in upcoming work, there are a lot of articles on the swift.org website that could migrate into this new combined documentation structure. Some of those articles may be able to just move over, which is great — others may need some updating or rework to switch them forward from one-off articles to ongoing documentation. We're tracking those migrations and updates in issues at swiftlang/docs.

Get involved

The content coverage is uneven, and we'd all like it to be better. As we go forward, we're delegating technical review to the relevant steering group — Language, Platform, or Ecosystem — to identify relevant reviewers and ensure accuracy.

There are a few ways to help:

49 Likes
2

Looks great! Has there been any discussion of allowing all or parts of the documentation to be downloaded locally? Perhaps as a PDF or ePub? Or at least the book? I don't see any mention, but third parties have been able to accomplish this, so it would be nice to have a first party solution.

8 Likes
3

Great job on this. Congregations.

A few questions on this @Joseph_Heck :

  1. Will version picker supported on the page?
  2. Will old release like release/6.3 be supported. Currently it looks like we only have main and latest.

It will be good if we can have all history versions hosted and switchable.

image
image2688Ă—644 165 KB

Screenshot is from VDC build of swift-book

1 Like
4

Also beside versioning, I hope some feature we discussed here can also be added in the future.

eg.

  • Default "edit page" button on the bottom to direct people to contribute more easily.
  • Default "star on GitHub" button to boost library status on GH.
2 Likes
5

Thanks to @Joseph_Heck and the people bringing the stdlib docs to swift.org for putting this together with the various teams. Documentation has historically been considered a weak spot for Swift in certain regards, particularly for cross-platform use outside Darwin platforms, hopefully we can turn it into a strength in the coming years.

5 Likes
6

This is extremely awesome work. I'm so glad to see that I can finally link people to stdlib docs on swift.org instead of apple.com . Not to mention all the other excellent documentation which is finally in the same place. Thank you & all who worked on it! :partying_face:

I just want to mention that I think using "latest" to refer to documentation for an unreleased version is pretty confusing. And especially weird given that just going to docs.swift.org takes you to "latest." I think it would be really nice to have "latest" be the latest actually released version & have a different tag for the unshipped release branch.

Otherwise you go to docs.swift.org and find functionality which hasn't been released yet!

One example is the Python documentation (e.g. uuid — UUID objects according to RFC 9562 — Python 3.14.7 documentation) which defaults to the most recently released version & has a "pre" (for "prerelease") tag for the next-to-be-released version.

7 Likes
7

@willft yeah, Its weird and I jumped forward a bit here. I choose to go with 6.4.x for latest to get this established, given how close we are to it landing as the release, primarily to make sure the build processing and CI would be smooth with this upcoming release.

Doing versioned docs with DocC has some existing challenges, and originally I'd only intended to set up latest and tack in the versioned pieces after, as we really need to do something to get canonical HTML tags in place so that the replicas don't cause search infrastructure to choose to just de-list the content.

Going forward, latest will not point to a pre-release like it is right now - it'll be what the current release is, and we'll be integrating doing the updates and transitions for these docs as a part of the Swift release process going forward, but we're not well integrated right now, so I stepped it forward to try and keep things simple, at the cost of some initial gaps.

5 Likes
8

The specifics of what this'll look like hasn't been nailed down, and we'll be working out both the details of how it looks, how it works, and how we'll drive it with data going forward. The general desire is to some way to navigate and choose to view a different version, and in addition to the example you're showing, we're also closely looking at how Swift Package Index enables is selection.

Screenshot 2026-08-26 at 10.41.36 AM
Screenshot 2026-08-26 at 10.41.36 AM2258Ă—1228 342 KB

Since this isn't something supported in the DocC-render single-page JS app today, I suspect we'll need to work around it with some selection mechanism in a wrapped header/footer, which this collection already uses, quite minimal today.

I'm not currently planning on assembling prior versions, primarily just due to constraints on time from the various folks that need to coordinate to assemble these pieces. We're aiming at growing forward and letting the back-versions fill out as we step the project forward.

1 Like
9

Speaking for myself, I've long wanted to publish straight through to both static HTML, generate PDFs, and create ePubs - and as you know, that's been a thought and gap with the DocC tooling since we transitioned to it. Fortunately, it's clearly not insurmountable, given the amazing community work to make that happen.

Setting up this content in the open source project, including building and assembling the results with open tooling and processes, sets us up nicely, and that the community can take advantage of it. We want to enable everyone to use this language effectively on the platform and system of their choice.

I'd also like to see a clear pathway for our content to a variety of formats, as well as a significantly improved developer experience to generate the docs (so you don't need to add a SwiftPM plugin to create local docs), and more flexibility in presentation - whether that through VS Code extension, a hosted website, or external apps that consolidate and present documentation content.

@0xTim recent work on Kiln that he posted about recently is really intriguing to me, and I haven't had to really explore that project in any depth. There's all kinds of depth we haven't started to plumb here that I think as a community we could assemble in front of us.

3 Likes
10

Ah yeah if it's just until the next release that's totally fine. Very reasonable choice. :+1:

1 Like
11

Nice job!

I took a look at the docs repo and noticed that there are a handful of issues labeled as "content migration". Is there an established owner or process for who takes on those migration issues specifically, or is it open for anyone in the community to pick one up?

12

Yeah, give me a bit there, as we're working on what works well for identifying approvers with the steering groups, and talking about how to ask for people's time respectfully across the various steering groups or working groups - who-ever and how-ever we end up delegating technical review to.

The issues seeded up there earlier cross all the steering groups, and they are primarily established so that we don't leave legacy content to linger under swift.org, loosing it. Some have been periodically maintained and updated, but quite a few have not - and at this point some perhaps should be reworked entirely, or just dropped.

After I've had more of a chance to coordinate with the various steering groups and we assemble some patterns of work that don't overwhelm either writers or reviewers, I hope to extend from "here's what we had, what do we do with it?" to more forward looking "what kind of content do we need:- to benefit the community, to flesh out information across the various platforms with a bit more consistency, to support using more of the Swift toolchain in broader contexts, or to make Swift more consistent or easy to utilize as a language. There's lots of potential areas.

As I teased months ago when we were setting up the docs proposal and working to get the basics established to enable the docs as it's own thing for Swift, I'll be actively engaging with anyone in the community who's interested in helping out, and helping to coordinate all the moving parts to broaden and support the documentation coverage for Swift in a broad number of areas. At least that's my hope!

13

This looks great and will make less people be confused and put off by Swift discussions commonly linking back to Apple's documentation site. I do have some queries I would like to get a bit clearer on elaborations on this project.

Is it intentional that the repository doesn’t have the documentation site as its website?

Is it intentional that PackageDescription documentation is not present on the site?

Would it be feasible to start making docs.swift.org the default documentation site eventually by making developer.apple.com/documentation redirect for each duplicated Documentation Catalog?

Could dynamic in url versioning be feasible (ie. docs.swift.org/release/x.x.x/documentation) be feasible where it dynamically provides the most recent release version based on the semantic version with a fallback to the most recently released version based on specificity.

Elaboration on URL scheme

Using release as a specifier would make some precedence for other version collections like nightly or pre-release. It could also make resolution simpler and faster but semantically latest can be understandable(ie. docs.swift.org/latest/6.4.0/documentation)

14

Which repository? swiftlang/swift? swiftlang/docs? one of the others that's included? And by website, do you mean a URL link from the GitHub repo that's supported in their interface?

In general, swiftlang/swift links off to www.swift.org intentionally as an introduction, but it's quite reasonable to add a URL link from the docs report to the canonical docs going forward. Once we're past the 6.4 release, that makes a lot of sense.

So here's the thing, it actually is on the site - for example: https://docs.swift.org/latest/documentation/packagedescription/ resolves (as does PackagePlugin), but they're not obviously listed. That's a choice we made due to a rather unfortunate side effect of DocC and aligning to what we'd prefer to present.

The default structure of DocC is set up very much to present all modules equally, but we'd like to collapse some of those together, nesting them together specifically - and we don't have a great way to accomplish that today while staying explicitly within the bounds of what DocC provides today. The Swift Standard Library is actually a collection of ~8-10 modules, worked around with a bit of special case trickery, Foundation (made of Foundation Essentials and Foundation Internationalization) is effectively the same, and Package Manager has the core docs plus the several additional modules that you identified.

In the work to set this up, we're explicitly hiding some of those modules, and working out what we can do to present them so that the result isn't a tumble of lego blocks all over your proverbial floor, but a bit more of a collected, obvious guide to find the information you're after.

re: developer.apple.com - the work we're doing here is independent of what and how Apple presents it's documentation, and (unsurprisingly) I can't speak to any plans or effects that overlap with developer.apple.com.

For the dynamic URL scheme - in essence, that's what we're doing, but we're keeping it significantly more simplified. The delta in documentation between a release such as 6.2.3 and 6.2.4 is so minor we didn't seethe value in maintaining an explicit URL for each point release, and we're sticking with docs for major and minor versions. - so /6.4/documentation instead of having each individual variation for 6.4.0, 6.4.1, and so on.

We tried to keep the URLS intentionally as short as we absolutely could - so including release as a URL slug felt redundant and unnessecary. The choice of /latest/documentation is a nod to worlds that we can't control - particular how Google and other search indexes deal with nearly identical content at different URLS. We're working on shimming in some canonical URLs here, but the lessons that @daveverwer and @finestructure shared with the DocC workgroup while were were discussing how this goes together was basically that Google "appears to hate it" when you change the canonical URL, but seems to be much happier with a simple, static URL that it can count on for long periods. (We believe adding in the canonical URL refs into the content will also help significantly, as will the great experimental HTML content work that @ronnqvist did to embed content into the HTML stubs to make it more much amenable to crawlers.)

The .../documentation/... is a constraint that I'd very much prefer to live without, with simpler URL redirection schemes - but that detail is deeply embedded in DocC's presentation today, and doesn't seem to be coming loose any time soon. We optimized for efficiency of operation, while still also stepping forward to provide both a current release, the development version, and as we step forward - past releases.

In general, getting the semantics of version - and what's canonical - included within the metadata of the HTML seems to be have the most immediate and biggest win, so that's what we're heading for today.

3 Likes