Previewing documentation locally
This guide walks through how to use the unidoc preview
tool to preview documentation locally on macOS 15. This guide won’t make any effort to explain how Unidoc itself works, it is merely intended to demonstrate how to preview multi-package documentation as quickly as possible.
In this guide, you will:
Launch and initialize a
mongod
instance in a Docker container,Build or install Unidoc on the macOS host,
Run an instance of
unidoc preview
on the macOS host,Generate documentation for the standard library, and
Generate documentation for two SwiftPM packages, one of which depends on the other.
1. Install Docker
The easiest way to preview documentation locally is to use Docker. You can download Docker Desktop for macOS from the official website.
2. Install Unidoc
Today, there are two main ways to install Unidoc — building it from source or downloading a pre-built binary.
Downloading a pre-built binary
Pre-built binaries are available for a limited set of platforms.
Platform | Architecture | Download |
---|---|---|
macOS 15 | arm64 | tar.gz |
Ubuntu 24.04 | arm64 | tar.gz |
Ubuntu 24.04 | x86_64 | tar.gz |
Ubuntu 22.04 | arm64 | tar.gz |
Ubuntu 22.04 | x86_64 | tar.gz |
You can download and install the binary under /usr/local/bin
like this:
unidoc-install.sh
UNIDOC_MIRROR=https://download.swiftinit.org/unidoc
UNIDOC_VERSION=0.20.1
UNIDOC_PLATFORM=macOS-ARM64
curl -L $UNIDOC_MIRROR/$UNIDOC_VERSION/$UNIDOC_PLATFORM/unidoc.tar.gz \
-o unidoc.tar.gz
tar -xf unidoc.tar.gz
sudo mv unidoc /usr/local/bin/unidoc
unidoc-install.shBuilding Unidoc from source
Unidoc is an ordinary SwiftPM executable product. You can build it for your macOS host like this:
unidoc-from-source.sh
git clone https://github.com/tayloraswift/swift-unidoc
cd swift-unidoc
swift build -c release --product unidoc
mv .build/release/unidoc /usr/local/bin/unidoc
unidoc-from-source.sh3. Launching a mongod
instance
Unidoc can configure a mongod
instance for you through the unidoc init
command. This tool takes a directory path as an argument, which it uses to persist the state of the database. In the example below, we will create the documentation database in a directory named unidoc
in your home directory.
unidoc init ~/unidoc
Please note that this will start a Docker container that runs continuously in the background. Therefore, if you want to dismantle the database, you must stop the container before deleting the persistence directory, otherwise it may recreate some of the files you delete.

You should see the
unidoc-mongod-container
running in the Docker Desktop GUI.
3. Running unidoc preview
The unidoc preview
tool is a simple web server that links and serves documentation for local Swift packages. Run it directly from the host like this:
unidoc preview
The unidoc preview
tool will start a web server on http://localhost:8080
.
Please note that to serve the necessary CSS and JavaScript the server expects to find the Assets
directory in the current working directory. These resources are included in the unidoc.tar.gz
archives, and if built from source, they are also available in the swift-unidoc
repository.

The
unidoc preview
start page.
4. Generating documentation for the standard library
Generate local documentation using the unidoc local
subcommand. To start off, open a third terminal and generate the documentation for the standard library (swift
).
unidoc local swift
You should be able to view the symbol graph and its documentation at http://localhost:8080/tags/swift
.

The standard library documentation. We generated it using the default Xcode toolchain, so it’s labeled
__Xcode
.
5. Generating documentation for SwiftPM packages
Now, let’s generate documentation for swift-collections, a popular SwiftPM package. Download the library’s source code using Git.
git clone https://github.com/apple/swift-collections
To generate documentation for a package, you need to tell Unidoc where to find the project. Because you downloaded the swift-collections
repository to a child directory, you can use -i swift-collections
for the project path.
unidoc local -i swift-collections
The default value for the project path is the current working directory (.
), so alternatively, you could navigate to the swift-collections
directory and run unidoc local
without any arguments.
cd swift-collections
unidoc local
cd -
You should be able to view the symbol graph and its documentation at http://localhost:8080/tags/swift-collections
.

The
swift-collections
documentation.
Finally, let’s generate documentation for a package that depends on swift-collections
. Download the source code for swift-async-algorithms to a sibling directory of swift-collections
.
git clone https://github.com/apple/swift-async-algorithms
unidoc local -i swift-async-algorithms

The
swift-async-algorithms
documentation. Observe that it has a linked dependency on theswift-collections
documentation you generated earlier.
Please note that when you link documentation for a SwiftPM package against another package, it is your responsibility to ensure that the two versions are ABI-compatible. Many SwiftPM packages are not ABI-stable, so you should always check that the root package is being built with the same versions of its dependencies as you generated their documentation from.