Configuration

This document describes the Kampose JSON configuration file, covering the fields used to locate source assemblies and topics, control output formatting and layout, configure references, and customize themes.

By default, Kampose reads the configuration from the kampose.json file in the current working directory. You can specify an alternate file path on the command line:

kampose build MyConfig.json

Note

Kampose resolves every relative configuration path against baseDirectory. If baseDirectory is omitted, it uses the directory containing the configuration file.

The JSON schema is published for validation and editor support. Validate configuration files against it out of band, using the schema that matches your installed Kampose version, rather than referencing it from the configuration file itself.

Configuration Options

The following sections describe the various configuration options available in the Kampose JSON configuration file. Each option controls different aspects of the documentation generation process, from source file locations to output formatting and theme customization.

baseDirectory

Specifies the root directory for resolving all relative paths in the configuration file.

When not specified, Kampose uses the directory containing the configuration file. All relative paths in the configuration are resolved from this directory.

Example

The following example sets a custom base directory for path resolution. Since the base directory is relative, it resolves against the directory containing the configuration file.

{
  "baseDirectory": "path/to/project",
  "assemblies": ["src/**/*.dll"],
  "topics": ["docs/**/*.md"]
}

outputDirectory (required)

Specifies the directory where Kampose writes all generated documentation files. Kampose creates the directory if it doesn't exist.

This setting is required.

Example

The following example specifies an output directory (site) relative to the base directory (/project):

{
  "baseDirectory": "/project",
  "outputDirectory": "site"
}

convention

Specifies the page layout and URL format for the generated documentation.

The default convention is docFx.

With the gitLab convention, the home topic is written to home.md, which GitLab Wiki serves as the front page, and the other pages are nested under it in the home folder. Because GitLab displays a page's file name as its title, the built-in Markdown theme starts each page with a front matter title that holds the original title. GitLab displays front matter titles by default from version 17.2. See CI/CD Integration for a pipeline that publishes the output to a GitLab wiki.

Example

The following example configures the .NET convention, where each type and member has its own documentation page:

{
  "convention": "dotNet"
}

baseUrl

Specifies the root URL for the documentation, which must be an absolute URI.

When a baseUrl is specified, all internal links become absolute URLs. Otherwise, Kampose generates relative URLs.

Leaving baseUrl unset is recommended so that the documentation can be used in different environments, including local development, without updating all internal links.

Example

The following example configures absolute URLs for a versioned documentation site:

{
  "baseUrl": "https://docs.example.com/v2/",
  "outputDirectory": "/var/www/docs/v2"
}

assemblies

Specifies glob patterns for locating .NET assembly files to document.

If an assembly appears in multiple locations, the first one found is used. You can use exclusion patterns to filter unwanted assemblies.

At least one assembly pattern is required when no topic patterns are specified.

Example

The following example includes release assemblies while excluding test and benchmark assemblies:

{
  "assemblies": [
    "src/**/bin/Release/**/*.dll",
    "!**/*Test*.dll",
    "!**/*Benchmark*.dll"
  ]
}

xmlDocs

Specifies glob patterns for additional XML documentation files or those not in the same location as their assemblies.

Example

The following example includes XML documentation from custom locations:

{
  "assemblies": [
    "dist/**/*.dll"
  ],
  "xmlDocs": [
    "docs/xml/**/*.xml",
    "third-party/docs/*.xml"
  ]
}

references

Configures how to link to documentation of third-party libraries referenced within the codebase being documented.

Kampose automatically handles references to standard .NET API types (System., Microsoft., etc.). Use this setting to link to documentation for third-party libraries or internal company documentation.

Each entry in the references array configures how to link to external documentation for a specific namespace or set of namespaces.

namespaces (required)

Specifies the namespaces that should be linked using this entry.

The matching is case-sensitive and the * wildcard can be used as the final segment to match any sub-namespaces.

This setting is required for each reference entry.

strategy (required)

Specifies the strategy used for linking to the external documentation. It can be one of the following:

This setting is required for each reference entry.

url (required)

Specifies the absolute base URL of the external documentation site. For the onlineSearch strategy, it is the search endpoint: Kampose appends a q query parameter that holds the fully qualified name of the code element.

This setting is required for each reference entry.

extension

Overrides the page extension that the strategy adds to generated URLs. Set it to an empty string to omit the extension. If omitted, the strategy's default extension is used. This setting has no effect on onlineSearch references.

Examples

The following example configures Kampose to use a search engine for Newtonsoft.Json references:

{
  "references": [
    {
      "namespaces": ["Newtonsoft.Json.*"],
      "strategy": "onlineSearch",
      "url": "https://duckduckgo.com/"
    }
  ]
}

The example below links to internal company documentation with custom file extensions:

{
  "references": [
    {
      "namespaces": ["MyCompany.SharedLib.*"],
      "strategy": "docFx",
      "url": "https://internal-docs.mycompany.com/sharedlib/",
      "extension": ".htm"
    }
  ]
}

topics

Specifies glob patterns for conceptual documentation files like guides, tutorials, and overviews. By default, it includes the Markdown files directly inside baseDirectory (*.md).

Kampose processes these files and converts them to the target format.

For a task-oriented explanation of topic metadata, hierarchy, and links, see Conceptual Topics.

Example

The following example includes documentation from multiple directories while excluding draft content:

{
  "topics": [
    "docs/**/*.md",
    "guides/**/*.md",
    "!docs/drafts/**"
  ]
}

Topic Front Matter

Markdown topic files may start with YAML front matter. Kampose reads this front matter as topic metadata and removes it from the rendered Markdown body.

The following keys have meaning to Kampose:

Example

---
title: Quick Start
summary: Learn how to configure and run Kampose for a .NET project.
---

# Getting Started

Special Topic Filenames

Certain filenames have special significance when organizing topics:

topicOrder

Specifies the explicit ordering for topics in the documentation navigation.

Topics are displayed in the order specified in this list. Each entry is a topic path relative to baseDirectory or a file name, with or without the extension, and matching is case-insensitive. Topics that are not listed follow the listed ones in alphabetical order by title, and entries that match no topic are ignored.

Example

The following example defines a specific order for key documentation topics:

{
  "topicOrder": [
    "docs/overview.md",
    "guides/installation",
    "guides/configuration.md",
    "advanced/customization"
  ]
}

topicHierarchy

Specifies the method for organizing topics into parent-child relationships.

The default value is none, meaning no hierarchy is applied.

Example

Directory hierarchy:

guides.md              → Parent topic
guides/
  ├── installation.md  → Child of guides.md
  └── advanced.md      → Child of guides.md

Index hierarchy:

guides/
  ├── overview.md      → Parent topic
  ├── installation.md  → Child of overview.md
  └── advanced.md      → Child of overview.md

Prefix hierarchy:

api.md                 → Parent topic
api.classes.md         → Child of api.md
api.classes.core.md    → Child of api.classes.md

assets

Configures the handling of static files in the documentation. Files are copied as-is and their include-relative directory structure is preserved beneath targetPath.

Each entry in the assets array specifies a set of files for a specific destination directory within the output directory.

source (required)

Specifies glob patterns for selecting files to copy directly to the output directory.

This setting is required.

Each positive include has its own hierarchy root: the directory prefix before the pattern's first wildcard. A matched file keeps the path beneath that root. For an exact-file include, the root is the file's containing directory. Exclusion patterns remove matches but do not define or change a root.

For example, docs/assets/**/* has the root docs/assets, so docs/assets/diagrams/setup-flow.svg retains diagrams/setup-flow.svg. A pattern with a wildcard in a directory name, such as docs/*/assets/**/*, has the root docs and retains the matched path below docs.

Multiple positive includes in one rule are evaluated with their own roots. If they select the same file and imply different retained paths, Kampose rejects the rule as ambiguous. Split or narrow the includes to give that file one unambiguous path.

targetPath

Specifies the directory within the output directory where the files are copied.

This setting is optional. If omitted, files are copied to the root of the output directory.

targetPath must be relative and cannot contain .. path segments. The complete generated path—targetPath plus the retained source path—must be unique across configured and theme assets. Files with the same basename are valid when their retained subdirectories differ; exact generated-path collisions are rejected.

Example

The example below demonstrates copying different asset types to separate directories:

{
  "assets": [
    {
      "source": ["company-logos/**/*"],
      "targetPath": "assets/branding"
    },
    {
      "source": ["legal-docs/**/*.pdf"],
      "targetPath": "downloads"
    }
  ]
}

In this example, company-logos/products/widget.svg is generated as assets/branding/products/widget.svg, while legal-docs/archive/terms.pdf is generated as downloads/archive/terms.pdf.

Topics should continue to link registered assets by source-relative path. For example, a topic at docs/guides/setup.md links docs/assets/diagrams/setup-flow.svg as ../assets/diagrams/setup-flow.svg; Kampose maps that reference to the generated asset URL for the selected convention.

theme

Specifies the theme to be used for generating the documentation pages.

The available themes depend on the convention used. Please refer to the themes documentation for a list of available themes.

The value is either the name of an installed theme or the absolute path of a custom theme directory that contains a theme.json file. If no theme is specified, Kampose uses the "classic" theme.

Example

The following example selects the classic theme:

{
  "theme": "classic"
}

themeSettings

Specifies theme-specific customization parameters that control appearance and behavior of the selected theme.

Available settings vary by theme and are defined by each theme's configuration. Please refer to the themes documentation for information about available themes and their specific parameters.

Theme setting names are case-insensitive. A setting that conflicts with a built-in global template variable is ignored and reported as a warning.

Example

The following example configures various theme settings for the classic theme (HTML):

{
  "themeSettings": {
    "projectName": "My Project",
    "faviconUri": "assets/favicon.ico",
    "pageFooter": "Copyright © {{now 'yyyy'}} [My Company](https://company.com)"
  }
}

Markdown settings can also accept an array of strings for multi-section content:

{
  "themeSettings": {
    "pageFooter": [
      "Copyright © {{now 'yyyy'}} [My Company](https://company.com)",
      "[Privacy Policy](/privacy) | [Terms](/terms)",
      "Built with Kampose"
    ]
  }
}

audit

The audit settings determine which aspects of the XML documentation should be checked and whether to proceed with documentation generation if issues are found.

These settings help ensure that the generated documentation meets quality standards by identifying missing or incomplete XML comments.

options

Specifies the documentation XML tags that should be checked. It can include the following options:

The default value is the minimum required documentation (e.g., [required]).

includeImplicitConstructors

Specifies whether to include implicit default constructors in the audit (default: false).

The default constructors generated by the compiler are not documented in XML and are typically excluded from audits and documentation.

However, if you want to ensure that all public constructors are explicitly defined and documented, you can set this option to true so that the audit reports implicit constructors as undocumented.

verifyExternalLinks

Specifies whether to verify external links in XML documentation comments and Markdown topics (default: false).

Kampose ensures all hyperlinks referenced in the XML documentation comments (<see> and <seealso> tags with href attributes) and topics are well-formed and valid. For internal links, it also checks that they point to a file generated by the same run. Files that are already in the output directory but were not generated, such as leftovers from an earlier build, do not count, and paths are compared case-sensitively.

For HTML output, an internal link with a fragment, such as guide.md#setup or #setup, must also name an id on the target page, or the name of an a element on it. Fragments are compared case-sensitively, as browsers do, and #top always refers to the top of the page. Markdown output is not checked for fragments, because the wiki that hosts the pages generates their heading anchors.

However, external links (those starting with http:// or https://) are not verified by default to avoid delays during documentation generation. By enabling this option, Kampose will actively check the accessibility of these external URLs and report any broken or unreachable links as audit issues.

Note

Enabling external-link verification can increase generation time, especially when the documentation contains many external links.

stopOnIssues

Specifies whether audit issues fail the run instead of being reported as warnings (default: false).

By default, Kampose reports audit issues and continues. When this option is true:

• XML documentation issues, or the absence of any XML documentation file, stop the run before any page is written.
• Invalid links, including links to missing anchors, stop the run after the pages are written, because links are verified against the generated files. The output directory then contains the generated files, but the run still fails.

In both cases, Kampose exits with code 3. This is particularly useful in continuous integration, where the failed run fails the pipeline.

Example

The following example enables auditing for minimum required documentation plus property value tags, and stops generation if issues are found in the XML documentation:

{
  "audit": {
    "options": ["required", "value"],
    "stopOnIssues": true
  }
}