Themes

Kampose themes define the templates, assets, parameters, and presentation of generated documentation. The selected documentation convention determines whether Kampose loads an HTML or Markdown theme.

HTML-Based Themes (DotNet/DocFx Convention)

When convention is dotNet or docFx, Kampose loads an HTML theme. The built-in Classic theme provides a responsive documentation website with navigation, search, and configurable page components.

Available Themes

The following table summarizes the available HTML themes:

Installing New Themes

To use a custom HTML theme, set theme to the absolute path of the theme directory. Alternatively, copy the theme directory into the themes/html/ directory of the Kampose installation and use the directory name as the theme identifier. A theme copied into the installation is removed when Kampose is updated or reinstalled.

Markdown-Based Themes (DevOps/GitLab Conventions)

When convention is devOps or gitLab, Kampose loads a Markdown theme. The generated files are suitable for systems such as Azure DevOps Wiki and GitLab Wiki that consume Markdown documentation.

Available Themes

The following table summarizes the available Markdown themes:

Installing New Themes

To use a custom Markdown theme, set theme to the absolute path of the theme directory. Alternatively, copy the theme directory into the themes/md/ directory of the Kampose installation and use the directory name as the theme identifier. A theme copied into the installation is removed when Kampose is updated or reinstalled.

Theme Configuration

Themes expose settings that customize their behavior and appearance. Configure them in kampose.json under themeSettings.

Each theme documents its available settings, including their purpose and usage. Consult the specific theme documentation to understand which settings are available and how to configure them.

Configuration Example

The following excerpt demonstrates basic theme configuration:

Note

This is a focused configuration excerpt. A complete configuration also requires outputDirectory.

{
  "theme": "classic",
  "themeSettings": {
    "pageFooter": "Copyright © {{now 'yyyy'}} [Example Corp](https://example.com)"
  }
}

Settings with Rich Content Support

Settings declared with the markdown parameter type accept Markdown and Handlebars expressions. The built-in themes use this type for settings such as page headers and footers.

Markdown settings accept either a single string or an array of strings. When an array is provided, the items are joined with newlines, offering a more readable and maintainable alternative to using escape sequences in JSON strings.

When configuring settings that accept Markdown content, follow these guidelines:

• Documentation Links: Prefix documentation-root-relative paths with ~/, for example [License](~/LICENSE). See URL resolution for document-relative, site-root-relative, and documentation-root-relative behavior.
• Template Integration: Markdown theme settings can use template helpers and template variables. Ordinary Markdown topic files cannot.
• Multi-Section Content: Use an array of strings to define content with multiple sections or lines without concatenation.

For comprehensive information on expression syntax, refer to the Handlebars documentation.

Creating Custom Themes

Kampose allows you to create custom themes by following a structured approach. This involves setting up the theme directory, creating the necessary files, and configuring the theme settings.

You can find the detailed steps for creating custom themes, including examples, in the theme authoring guide.