Skip Navigation
ArticleArticle

Configuration Reference

Configure DocCStatic for your documentation needs.

Overview

The Configuration Reference type controls all aspects of documentation generation, from which targets to document to the visual appearance of the output.

Basic Configuration

At minimum, you need to specify the package and output directories:

let configuration = Configuration(
    packageDirectory: URL(fileURLWithPath: "/path/to/package"),
    outputDirectory: URL(fileURLWithPath: "/path/to/docs")
)

Target Selection

By default, DocCStatic documents all targets in your package. To document specific targets only:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    targets: ["MyLibrary", "MyUtilities"]
)

Dependency Policies

Control which dependencies are included using DependencyInclusionPolicy:

Include All Dependencies (Default)

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    dependencyPolicy: .all
)

Exclude Specific Packages

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    dependencyPolicy: .exclude(["LargeDependency", "InternalOnly"])
)

Include Only Specific Packages

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    dependencyPolicy: .includeOnly(["PublicAPI"])
)

Exclude All Dependencies

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    dependencyPolicy: .none
)

Link to the hosted documentation of dependencies that are not documented:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    dependencyPolicy: .exclude(["MyDependency"]),
    externalDocumentationURLs: [
        "MyDependency": URL(string: "https://example.com/mydependency")!
    ]
)

When a page refers to a symbol of a module that is not part of the generated documentation, the reference links to the symbol’s page below the module’s base URL, at <base URL>/documentation/<module>/<path>/. A key is a module name or the name or identity of a package, which covers all modules of that package. References to modules without a base URL are shown as unlinked text. See Cross-Package Linking for details.

Search Configuration

Enable client-side search with Lunr.js:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    includeSearch: true
)

When search is enabled, the generator:

  1. Creates a search-index.json file with all searchable content

  2. Includes the Lunr.js library

  3. Lists content matches below the tree when the reader types in the filter field of the navigation sidebar

  4. Provides incremental search across all documentation

Theme Configuration

Customise the visual appearance with ThemeConfiguration. See Custom Themes for theme files, theme directories and feature switches.

Built-in Themes

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    theme: ThemeConfiguration(builtInTheme: .classic)
)

Theme Names, Files and Directories

resolveTheme(_:includeDarkMode:customCSS:warningHandler:) resolves a string the same way as the --theme option: a theme directory, a theme-settings.json file, or the exact name or alias of a built-in theme.

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    theme: try ThemeConfiguration.resolveTheme("MyTheme")
)

Custom Accent Colour

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    theme: ThemeConfiguration(
        accentColour: "#ff5500",
        includeDarkMode: true
    )
)

Disable Dark Mode

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    theme: ThemeConfiguration(builtInTheme: .default, includeDarkMode: false)
)

Custom CSS

Append custom CSS after the theme’s own stylesheets:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    theme: ThemeConfiguration(
        builtInTheme: .default,
        customCSS: """
        .my-custom-class {
            font-weight: bold;
        }
        """
    )
)

Verbose Output

Enable detailled logging during generation:

let configuration = Configuration(
    packageDirectory: packageURL,
    outputDirectory: outputURL,
    isVerbose: true
)

This outputs progress messages including:

  • Symbol graph generation status

  • DocC conversion progress

  • Page rendering information

  • Asset writing confirmation

Complete Example

A fully-configured example:

let configuration = Configuration(
    packageDirectory: URL(fileURLWithPath: "."),
    outputDirectory: URL(fileURLWithPath: ".build/docs"),
    targets: ["MyLibrary"],
    dependencyPolicy: .exclude(["TestSupport"]),
    externalDocumentationURLs: [
        "MyDependency": URL(string: "https://example.com/mydependency")!
    ],
    includeSearch: true,
    theme: ThemeConfiguration(
        accentColour: "#007aff",
        includeDarkMode: true,
        customCSS: ".header { background: linear-gradient(...); }"
    ),
    isVerbose: true
)

See Also