Configuration¶

Tarn's configuration controls page badges, navigation decoration, fonts and colours. It styles the site's existing navigation and does not create a section layout. The theme selection belongs in zensical.toml:

[project.theme]
name = "tarn"

Tarn requires Python 3.11 or newer and pins Zensical to version 0.0.73. Its navigation template overrides are checked against that release.

Tarn settings¶

Tarn's own settings live under project.extra.tarn. Each setting is optional. An omitted setting retains its default. Project values in sections and labels replace only the matching entries, so other defaults remain in effect.

This example hides page badges, changes three section classifications and defines two translated badge labels:

[project.extra.tarn]
badges = false

[project.extra.tarn.sections]
getting-started = "tutorial"
release-notes = "secondary"
examples = "primary"

[project.extra.tarn.labels]
tutorial = "Tutoriel"
howto = "Procédure"

For mkdocs.yml configuration read by Zensical, use the equivalent structure under extra.tarn. MkDocs itself has not been verified.

Decoration and credit switches¶

enabled = false hides badges and navigation decoration. badges = false hides only badges, while navigation = false hides only navigation decoration. Neither page metadata nor a section mapping can override a disabled switch. These switches leave Tarn's stylesheet and other theme styling in place.

The default footer reads “Made with Zensical and the Tarn theme”. Setting project.extra.generator = false hides both credits. credit = false under project.extra.tarn hides only Tarn's credit. Project copyright text is retained. credit_url changes Tarn's link destination. An empty value uses the default URL.

Section classifications¶

Each key in sections is the first segment of a site-relative URL, without slashes. A direct page such as reference.html uses reference as its key. Values are tutorial, howto, reference, explanation, primary, or secondary. primary gives ordinary navigation without a dot. secondary gives quieter navigation separated from primary sections. Neither gives an automatic badge.

An unknown URL segment defaults to secondary. An invalid value in an explicit sections mapping falls back to primary, even when the key matches a built-in alias. The homepage defaults to primary regardless of its navigation position. External links are secondary and are not classified by their target folder. Nested navigation uses the first linked page, or the section index when Zensical selects one. Explicit page badges do not change section classification. For the complete default aliases, see Section folders.

Keep secondary entries together at the end of nav to place them at the right of the tab bar, or below a separator in the sidebar. Tarn preserves the order of the project's navigation. See Name your sections for a mapping task.

Badge labels¶

Label overrides affect badges. Navigation titles remain those in the project's nav configuration.

Page front matter¶

Page metadata in the opening YAML block can override the badge classification:

---
tarn:
  type: howto
---

tarn.type overrides the automatic badge on that page. Values are tutorial, howto, reference, and explanation. Set none to suppress the badge. Other values produce no badge. If tarn.type is absent, the badge uses the page URL classification, including section overrides. enabled = false or badges = false suppresses badges even when the page specifies a valid type.

See Set or remove a page's badge for examples.

Zensical defaults supplied by Tarn¶

These defaults are in mkdocs_theme.yml. A project setting replaces the corresponding theme default.

The icon.admonition defaults are:

See sidebar navigation for a complete feature-list example.

Palettes¶

Tarn supplies default and slate colours. An empty palette list uses a light fallback. Light-only and dark-only lists are supported. Set primary = "custom" and accent = "custom" to retain Tarn's blue link and control colours. Named Zensical primary and accent colours remain effective when explicitly selected. Arbitrary custom scheme names are not additional Tarn palettes. See Adjust a colour for CSS overrides.

To start new visitors in light or dark mode while keeping the mode toggle, see Choose the default colour mode. Tarn's default remains automatic, following the system preference unless a reader has saved a choice. The default light palette offers lucide/moon with the label “Switch to dark mode”. The dark palette offers lucide/sun with the label “Switch to light mode”.

Fonts and CSS¶

Configured fonts use Zensical's font loader. font = false disables that loader and uses the upstream system fallback unless a project supplies its own fonts. Tarn does not force an unloaded Atkinson font. See self-host the fonts.

Tarn's stylesheet loads before Zensical's configured font declarations and the project's extra_css. Project CSS can override Tarn's variables. Branding assets use Zensical's logo and favicon theme settings, as shown in Add a project logo.

Local templates¶

A local overrides/main.html can preserve Tarn's styles and badges by extending its named base template:

{% extends "tarn.html" %}
{% block extrahead %}
  {{ super() }}
  <meta name="example" content="local override">
{% endblock %}

Set custom_dir = "overrides" in project.theme. Extending Zensical's base.html directly bypasses Tarn's template blocks.

Generated site files¶

Zensical 0.0.73 copies theme package files into generated sites, including __init__.py, __pycache__/__init__.cpython-<version>.pyc, and mkdocs_theme.yml. This is a verified limitation of the pinned release. Tarn does not remove these files automatically.

The following project-level configuration excludes these paths from the output:

[project.plugins.exclude]
glob = ["__init__.py", "__pycache__/*", "mkdocs_theme.yml"]

If the project already defines this table, add the patterns to its existing glob list. The patterns also exclude documentation assets with matching paths. This configuration belongs at project.plugins.exclude, outside project.theme and project.extra.tarn. Theme defaults merge into project.theme and cannot set this project-level plugin configuration.

The package check builds sites with an installed wheel. It reproduces the known files in the minimal example without exclusions, then requires clean output with these exclusions. Tarn's own documentation also uses the exclusions. See the generated-site checks for the verification details.