0.19.6

What's Changed

• Improved the ergonomics of the unidoc local command — it will now build the SwiftPM project in the current working directory if given no arguments, or the package specified by -i/--project-path if supplied.
• Added an overload disambiguation heuristic that automatically selects the documented overload, if exactly one overload among the choices has an associated doccomment and none of the others do.
• Trailing parentheses in symbol links are now meaningful, and will exclude struct, enum, class, actor, typealias, protocol, associatedtype, deinit, and var declarations.
• The absence of trailing parentheses in symbol links is now meaningful, and will exclude macro declarations only.

Full Changelog: 0.19.5...0.19.6

0.19.5

This release fixes a regression introduced in 0.19.4, in which @_exported symbols would cause false positives in the ambiguous symbol link checker, if the fully-qualified symbol link written spans three or more modules that re-export one another.

0.19.4

What's Changed

• fix module name shadowing problem preventing compiling Unidoc itself on macOS Sequoia by @tayloraswift in #344
• enable writing codelinks that resolve through @_exported paths and serve HTTP redirects for @_exported symbols by @tayloraswift in #345
• add definitions for bridgeOS and add missing Swift 6 stdlib modules to the standard library recipe by @tayloraswift in #347

Full Changelog: 0.19.3...0.19.4

0.19.3

This release makes the project compile with Swift 6.0.

This release also enables using Swift 6.0 as the compiler backend for building packages (this is different from compiling Unidoc itself!) and also disables several Unidoc assertions that collide with known regressions in the Swift 6.0 compiler.

• swiftlang/swift#76499
• swiftlang/swift#76559

Please note, on macOS, using a downloadable non-Xcode 6.0 toolchain as a package compiler backend is not recommended. In particular, you are likely to run into swiftlang/swift#76561 !

0.19.2

This release fixes a bug that caused SwiftPM packages that use uppercase letters in their project directory names to fail to compile on case-sensitive file systems.

Full Changelog: 0.19.1...0.19.2

0.19.1

What's Changed

• Optimized dynamic linker for Symbol Graphs with ABI ≥ 0.11.0
• Add support for visionOS @available markers

Unidoc 0.19

As some may already be aware, Swift Unidoc is a documentation engine that supports rendering documentation for a package and its dependencies, with symbol links that cross module and even package boundaries. This release introduces the unidoc preview and unidoc local tools, which enable compiling and browsing rendered documentation on your local machine.

What’s the update for?

Although Unidoc has existed for a long time now, effectively writing documentation that takes full advantage of its feature set has historically been hampered by several obstacles:

• Cross-package link resolution occurs at link time, on the server side, which prevented the compiler from diagnosing broken cross-package links.
• Because cross-package links appear syntactically identical to package-internal links, this prevented the compiler from effectively diagnosing broken links at compile time at all.
• Because it is difficult (if not impossible) to model the entire Swift package ecosystem locally, in practice, iterating with Unidoc required interacting with the centralized Swiftinit database.
• This also precluded using Unidoc as a CI validation step, as the CI pipeline would have to manage a build lifecycle on Swiftinit, which is very logistically complex.

Validate your links locally!

Unidoc 0.19 completely overhauls Unidoc’s compilation model such that all link resolution now takes place at compile time, on the client, without having to interact with Swiftinit at all. This allows you to iterate on your documentation locally with the confidence that your documentation is valid before even committing it in Git, or pushing it to GitHub.

Prebuilt binaries now available!

On select platforms (x86_64 Ubuntu 24.04 and aarch64 macOS), we now provide pre-built toolchains that can be installed without compiling Unidoc from source. The downloadable archives also include a copy of the web assets needed to browse rendered documentation locally.

Get started now!

You can get started with local documentation right now by following the Unidoc Quickstart guide. Setting up Unidoc for the first time has also become much easier, as the unidoc tool now provides a unidoc init subcommand that can automatically configure and initialize a local deployment on Linux and macOS.

0.18.0

it’s been a long time since the last ‘proper’ release, and we got in the bad habit of not writing release notes, so here’s a quick rundown of the major changes since 0.8.0.

• Unidoc now supports macOS (#169, #210)
• Unidoc now features an intrapage navigation sidebar on pages with section headings (#269)
• Generic extension blocks now have clickable section anchors (#274)
• Unidoc now correctly handle the case where packages refer to their dependencies by non-canonical names (#146)
• Underscored declarations now appear under a collapsed section (#147)
• Improved auto-generated curation of “miscellaneous” symbols (#150)
• Unidoc can now resolve documentation links to section headings (#195)
• Unidoc can now render IDE-style tooltips, and also export them to external websites (#209)
• Fixed an issue causing the server to hang indefinitely when submitting forms on Safari (#227)
• Unidoc can now render IDE-style symbol references in code snippets (#228, #245, #259, #260, #261)
• Unidoc can now display documentation for packages that lack a stable release tag (#232)
• Unidoc now correctly detects executable targets in pre-5.3 SwiftPM manifests (#241)
• Unidoc now supports “article-only” documentation, notably, TSPL (#276)
• Unidoc now allows disabling HTTPS in local development mode (#288)
• Unidoc now supports previewing documentation for multiple local packages at once (#289)
• Most Unidoc tools have been migrated to swift-argument-parser and now display richer help (#296)
• Unidoc now supports prerelease bounds in dependency requirements (#302)
• Unidoc can now compile markdown documentation containing hyperlinks with schemes besides https:// (#304)
• Unidoc can now compute and and display ABI compatibility metric for a documentation volume (#305)
• Unidoc now preserves the generic parameter substitutions in same-type constraints (#306)
• @Joannis made his first contribution in #290

Full Changelog: 0.8.0...0.18.0

0.8.0

Unidoc 0.8.0 was focused on improving support for rich media and structured tutorials, in line with what the DocC tool supports.

✂️ Snippets

Unidoc 0.8.0 now supports Swift Snippets, as specified in SE-0356. A complex example of Snippets in use can be found in the newly-published swift-png documentation.

Snippets support captions and slicing, and can display inline source citations if the documentation has been associated with a GitHub repository.

🎩 Tutorials

Unidoc 0.8.0 now supports structured tutorials, specifically, the @Tutorials, @Tutorial, and @Article block directives familiar to DocC users. Unidoc 0.8.0 can diff and highlight @Code blocks, similar to DocC. Like Snippets, tutorial code can also display inline source citations when linked to a GitHub repository.

Unidoc 0.8.0 also supports rich media, and can now display GitHub-hosted images inline in rendered documentation.

Most of the newly-supported block directives are available in all forms of documentation, not just @Tutorial blocks. The full list of supported block directives is:

• @Article
• @Chapter
• @Code
• @Comment
• @Column
• @ContentAndMedia
• @Documentation
• @DocumentationExtension
• @Downloads
• @Forums
• @Image
• @Intro
• @IsRoot*
• @Metadata
• @Resources
• @Row
• @SampleCode
• @Section
• @Snippet
• @Stack
• @Steps
• @Step
• @TechnologyRoot*
• @TutorialReference
• @Tutorial
• @Tutorials
• @Video
• @Videos
• @Volume

Note: @IsRoot/@TechnologyRoot can be detected and validated, but currently has no effect.

A live example of a rendered tutorial can be found in SwiftSyntax By Example.

🪞 Other improvements and bug fixes

• We improved the quality of the symbol graph compiler’s diagnostics, and associated more of the emitted diagnostics with source locations.
• We added tests and fixed a number of bugs in the cross-package link resolver.
• We added some optimization passes to the symbol graph compiler which should result in slightly smaller documentation archives.
• We added support for linkable - term <term name>: lists.
• The symbol graph compiler can now detect magical aside blocks in nested markup regions (#143 notwithstanding).
• The symbol graph linker can now sanitize external links, rewrite references to Apple Developer Docs if it can find a local copy of the target documentation, and remove nofollow from links to trusted domains, such as swift.org or wikipedia.org.
• The symbol graph linker now includes @_spi symbols, deprecated symbols, and typealiases in fuzzy search results. (We received feedback that these symbols are actually quite common search subjects, as developers are frequently searching for information about “gray” API.) This will be gradually rolled out on Swiftinit over the coming weeks.
• The symbol graph linker can now compress search archives with gzip, which may improve performance for some clients.
• The symbol graph linker can now resolve cross-package references to inherited symbols, such as Int.max (FixedWidthInteger.max).
• doc: links now behave identically regardless of syntax (<doc:_> vs [anchor text](doc:_)) used.
• The rendered documentation now includes OpenGraph metadata tags.
• The rendered documentation no longer displays a second “Symbols” pie chart for documentation coverage, as this was entirely redundant.
• The rendered documentation now displays statistics about @_spi declarations.
• The documentation server no longer sends unnecessary headers with 304 Not Modified responses.
• We improved the appearance of wide code blocks on mobile.
• We tweaked the package scoring algorithm so that popular open source packages now get updated even more frequently.

0.7.0

there are few obvious user-facing changes in this release, but a lot has shifted around in the code base since 0.6.

• Symbol graph build system now correctly runs git submodule update --init
• Symbol graph compiler can now recover from a Swift compiler crash (which sadly happens all too often…)
• Symbol graph compiler now uses a separate scratch directory from .build, which should make it easier to run it in a docker container
• Trailing slashes are now allowed in the Unidoc codelink format
• Admins can now inspect all of the package names and aliases associated with a package
• Admins can now change the preferred name of a package
• Server-side symbol graph linker now runs in the background as needed
• Server-side symbol graph linker can now export compiled symbol graphs to Amazon S3, which should greatly reduce the amount of disk space Unidoc requires
• Server-side symbol graph linker can now compress compiled symbol graphs with DEFLATE
• Admins can now view total server error (5xx) count
• Admins can now view global mongod ping times
• Admins can now manually uplink symbol graphs from the web UI
• Uplinking old documentation no longer generates new activity feed entries
• Fixed #123
• Symbol graph compiler now supports packages with dots in their names
• Symbol graph compiler can now collect information about available version-specific Package.swift manifests, and displays it in the web UI
• Added quick links to the web UI homepage
• Web server now queries from the fastest available mongod replica (when replication is enabled), which should reduce the amount of times people see pictures of Margot Robbie crying
• Upgraded swift-mongodb dependency to obtain some critical MongoDB driver bugfixes
• Enum cases are now displayed in a separate section in the web UI
• Protocol requirements now also benefit from autogenerated ‘See also’ sections
• Admins can now change robots.txt without restarting the server
• TikTok Bytespider is now blacklisted by default (sorry ByteDance)
• Adjusted the package scoring formula (we are slowly becoming swiftpackageindex :( )
• @available(obsoleted) symbols now render in grayed-out font in the web UI