Cross-Package Linking

Overview

DocCStatic generates documentation with relative paths, ensuring links work correctly whether viewing locally via file:// URLs or hosting on a web server. This article explains how cross-package linking works and how to configure it.

Relative Path Resolution

All links in the generated documentation use relative paths calculated at generation time. For example, a symbol in module A linking to a symbol in module B uses paths like:

<a href="../../moduleb/symbol/index.html">Symbol</a>

This approach ensures:

• Local viewing: Documentation works directly in a browser via file:// URLs

• Portable output: The entire documentation directory can be moved without breaking links

• Simple hosting: Any static file server can host the documentation

Linking Within Your Package

Links between symbols, articles, and tutorials within the same module are automatically resolved. DocCStatic uses the standard DocC reference syntax:

See ``MyOtherType`` for more information.

For an introduction, read <doc:GettingStarted>.

These references become relative HTML links in the output.

Cross-Module Links Within the Same Package

To link between different modules in the same package (e.g., from your CLI tool’s documentation to your library’s documentation), use the doc:// URL scheme in body text:

For programmatic access, see the <doc://MyLibrary/documentation/MyLibrary> library.

Configure the generator using <doc://MyLibrary/documentation/MyLibrary/Configuration>.

DocCStatic’s post-processor automatically resolves these links to relative URLs pointing to the correct module’s documentation. Note that these links must appear in regular body text, not in Topics sections.

Linking to Dependencies

When documenting dependencies alongside your main package, links to dependency symbols are resolved relative to the dependency’s documentation location:

docs/
├── documentation/
│   ├── mypackage/
│   │   └── mytype/        # Links to ../mydependency/deptype/
│   └── mydependency/
│       └── deptype/

Cross-Module Linking with Dependencies

DocCStatic supports linking to symbols in external documentation archives using the doc:// URL scheme. This uses the underlying DocC infrastructure for cross-module linking.

Using Pre-Built Documentation Archives

When you have pre-built documentation archives from other packages, use the --dependency flag:

docc-static generate \
    --scratch-path /tmp/build-mypackage \
    --package-path ~/MyPackage \
    --dependency /path/to/OtherPackage.doccarchive \
    -o /tmp/build-mypackage/docs

You can specify multiple dependencies by repeating the flag:

docc-static generate \
    --scratch-path /tmp/build-mypackage \
    --package-path ~/MyPackage \
    --dependency /path/to/PackageA.doccarchive \
    --dependency /path/to/PackageB.doccarchive \
    -o /tmp/build-mypackage/docs

Writing Cross-Module Links

In your documentation, reference symbols from dependency archives using the doc:// scheme:

See <doc://SwiftDocC/documentation/SwiftDocC/DocumentationContext> for details.

The bundle identifier (e.g., SwiftDocC) must match the bundle identifier of the dependency archive.

External Link Support

All documentation generated by docc-static automatically includes external link support metadata, allowing other packages to use your documentation as a dependency.

External Documentation URLs

For linking to external documentation (e.g., Apple’s developer documentation or other hosted docs), use the -e / --external-docs flag or externalDocumentationURLs.

Command Line

docc-static generate \
    -e 'com.apple.documentation=https://developer.apple.com' \
    -e 'SwiftNIO=https://swiftpackageindex.com/apple/swift-nio' \
    -o ./docs

Library API

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    externalDocumentationURLs: [
        "com.apple.documentation": URL(string: "https://developer.apple.com")!,
        "SwiftNIO": URL(string: "https://swiftpackageindex.com/apple/swift-nio")!
    ]
)

Writing External Links

In your documentation, use doc:// URLs with the bundle identifier matching your external URL mapping. For Apple’s documentation, the bundle identifier is com.apple.documentation:

Types must conform to <doc://com.apple.documentation/documentation/swift/Hashable>
to be used as dictionary keys.

This becomes a link to Apple’s Hashable documentation.

For other external packages, use their bundle identifier:

See <doc://SwiftNIO/documentation/NIOCore/Channel> for the channel abstraction.

Unresolved References

When a reference cannot be resolved and no external URL is configured, DocCStatic:

1. Renders the text without a link

2. Generates a warning in the result

3. Logs the issue in verbose mode

let result = try await generator.generate()
for warning in result.warnings {
    print(warning) // [warning] Unresolved reference: doc:MissingPackage/Symbol
}

Best Practices

Organise Your Documentation Structure

Keep your documentation well-organised for cleaner relative paths:

package/
├── Sources/
│   └── MyLib/
│       └── MyLib.docc/     # Documentation catalogue
└── Package.swift

Use Consistent Package Names

When referencing external packages, use the exact package name as it appears in your Package.swift dependencies.

Verify Links in Output

After generation, spot-check links by:

1. Opening index.html in a browser

2. Navigating to pages with cross-package references

3. Verifying the links work correctly

Handle Missing Dependencies Gracefully

If you expect some dependencies to be unavailable, configure external URLs:

let configuration = Configuration(
    // ...
    externalDocumentationURLs: [
        "com.apple.documentation": URL(string: "https://developer.apple.com")!
    ]
)

Troubleshooting

Links Are Broken When Viewing Locally

Ensure you’re opening the root index.html and navigating from there, rather than opening individual pages directly.

External Links Not Working

Verify the URLs in externalDocumentationURLs are:

1. Valid, fully-qualified URLs

2. Pointing to the root of the documentation, not a specific page

3. Using the exact package name as the dictionary key

Missing Cross-References

Enable verbose mode to see which references couldn’t be resolved:

let configuration = Configuration(
    // ...
    isVerbose: true
)