enum DependencyInclusionPolicy DependencyCross-Package Linking
Understand how DocCStatic handles links between packages.
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., Swift) 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.
Symbols Outside the Generated Documentation
Pages often refer to symbols of modules that the generated documentation does not contain, for example when a dependency is excluded (the default of the command line tool). Such references appear as
-
type names in declarations, such as parameter, return and property types, and attributes such as property wrappers;
-
related types, such as the protocols a type conforms to or the class it inherits from;
-
symbol links in documentation comments and articles, such as
``Other, that DocC resolved; andModule/Symbol`` -
topics listed in Topics or See Also sections.
DocCStatic never links these to pages that do not exist. Without an external documentation URL for the symbol’s module, a reference is shown the way DocC and its renderer show references they cannot resolve: a type name in a declaration and a related type as unlinked code (a related type qualified with its module, such as Other), a symbol link as code naming the symbol’s path, such as Other, and a topic is left out of its group. A group, and a section, with nothing left to list is left out together with its heading.
Web links in a hand-written See Also section, such as - [Colour theory primer](https://example, are listed with their titles, like any other topic.
External Documentation URLs
When the documentation of a module is hosted elsewhere, give its base URL with the -e / --external-docs option or external. References to that module’s symbols then link to their pages below the base URL, following DocC’s path convention:
<base URL>/documentation/<module>/<path>/
The module and path are in lower case, as DocC writes them. The base URL is the root of the hosted documentation and does not include /documentation.
The key of each URL can be
-
the name of a module, such as
My, ignoring case (hyphens and underscores are interchangeable, as Swift turns the hyphens of a target name into underscores); orDependency -
the name of a package dependency, as declared in its manifest, or its identity (the last component of its location), which applies the URL to every module of that package.
A module’s name often differs from the name of its package, so either can be used. If both a module and its package have a URL, the module’s URL is used.
Command Line
docc-static generate \
-e MyDependency=https://example.com/mydependency \
-e MyOtherPackage=https://example.com/myotherpackage \
-o ./docs
Library API
let configuration = Configuration(
packageDirectory: packageURL,
outputDirectory: outputURL,
dependencyPolicy: .none,
externalDocumentationURLs: [
"MyDependency": URL(string: "https://example.com/mydependency")!,
"MyOtherPackage": URL(string: "https://example.com/myotherpackage")!
]
)
Limits
Only references that DocC resolved can be linked: DocCStatic uses the path DocC computed for the symbol, including any disambiguation suffix of an overloaded symbol, such as mixed(with:)-1a2b3, and the names of enclosing types. These paths match the hosted documentation when it was built by DocC from the same version of the dependency. References that DocC could not resolve, for example in a module whose documentation catalogue is converted without the dependency’s symbols, are shown as DocC shows them, without a link.
Writing External Links
In your documentation, you can also use doc:// URLs whose bundle identifier matches a key of the external URL mapping:
See <doc://MyDependency/documentation/MyDependency/SomeType> for details.
This becomes a link to the page below the base URL of My. A doc:// link to a page of a documented module that is not generated is left as text.
Best Practices
Organise Your Documentation Structure
Keep your documentation well-organised for cleaner relative paths:
package/
├── Sources/
│ └── MyLib/
│ └── MyLib.docc/ # Documentation catalogue
└── Package.swift
Configure Hosted Documentation of Dependencies
If you do not document a dependency yourself but its documentation is hosted, configure its base URL so that references to its symbols remain links:
let configuration = Configuration(
// ...
externalDocumentationURLs: [
"MyDependency": URL(string: "https://example.com/mydependency")!
]
)
Verify Links in Output
After generation, spot-check links by:
-
Opening
indexin a browser.html -
Navigating to pages with cross-package references
-
Verifying the links work correctly
Troubleshooting
Links Are Broken When Viewing Locally
Ensure you’re opening the root index and navigating from there, rather than opening individual pages directly.
External Links Not Working
Verify the URLs in external are:
-
Valid, fully-qualified URLs
-
Pointing to the root of the documentation, not to
/documentationor a specific page -
Keyed by the module name, or by the name or identity of the package that provides it
Missing Cross-References
DocC reports the links it cannot resolve while it converts the documentation. Enable verbose mode to also see which dependencies are skipped and which modules external documentation URLs apply to:
let configuration = Configuration(
// ...
isVerbose: true
)