Configuration reference¶

Ulwazi works with a minimal conf.py:

extensions = ["ulwazi"]
html_theme = "ulwazi"

Everything else on this page is optional. If you don’t set a value, Ulwazi either falls back to a hard-coded default (so your build still works), or simply doesn’t render the feature that value controls. This page lists every Ulwazi-specific setting so you know what’s available and what happens if you skip it.

Note

For a baseline example with explanatory comments, see docs/default-conf.py in the repository – this is the easiest way to start using Ulwazi. It enables optional Sphinx extensions; install their packages in your documentation environment too.

Top-level configuration values¶

These are set directly in conf.py.

Setting	Default if unset	Purpose
`localtoc_max_depth`	`3`	Limits the local table of contents to H2–H4 on a page with an H1 title. Set to `-1` or `None` to show every heading level.
`slug`	`""`	Path segment for the project’s hosted documentation, used to prefix links on the bundled 404 page. For example, use `"ulwazi"` for `documentation.ubuntu.com/ulwazi/`.
`notfound_enabled`	`True`	Set to `False` to opt out of Ulwazi’s automatic `sphinx-notfound-page` activation and 404 defaults. If `notfound.extension` is also explicitly listed, it remains active.
`ulwazi_structured_toc_styling`	`True`	Set to `False` to opt out of Ulwazi’s temporary styling for sphinx-structured-toc’s `domain`/`slice` blocks (see below). Only applies when that extension is loaded.
`ulwazi_structured_toc_separator_color_light`	`""`	Overrides the light-theme vertical separator colour drawn between slice items (default: Ubuntu orange). Accepts any valid CSS colour (hex, named, `rgb()`, etc.).
`ulwazi_structured_toc_separator_color_dark`	`""`	Same as above, for the dark theme (default: white).
`highlight_language`	`"none"`	Sphinx’s fallback language for code blocks without an explicit language. Ulwazi defaults it to `"none"` (plain, unhighlighted code) when unset in `conf.py` or on the command line.

Ulwazi also supplies a 404.html template and chooses the 404 URL prefix from the Read the Docs canonical URL when available. Explicit notfound_template and notfound_urls_prefix settings take precedence. List "ulwazi" before "sphinx_modern_pdf_style" in extensions to enable Canonical PDF branding; Ulwazi stages the logo in the LaTeX output directory.

Default HTML title¶

When html_title is unset, Sphinx’s own default is "{project} {release} documentation" with release defaulting to an empty string – which duplicates the word for projects named like project = "Project documentation" (rendering “Project documentation documentation”). Ulwazi instead computes the default from project (plus release when set) and appends the " documentation" suffix only when the project name does not already end with it:

# project = "Project documentation", release unset
html_title == "Project documentation"  # not "Project documentation  documentation"

Explicit html_title settings always win, including Sphinx’s -D command-line option (the value is a plain string, so -D html_title=... works here, unlike the set-typed MyST setting above).

Structured-TOC styling (temporary)¶

sphinx-structured-toc’s domain/slice blocks ship with only minimal CSS – no bulleted-list removal, indentation, or themed separator colour; see the extension’s own CSS reference. Until the extension grows equivalent styling of its own, Ulwazi fills that gap: it removes the bullets and indent from the slice list, draws the vertical separators between slice items in the brand colour, and keeps visited links looking the same as unvisited ones, inside these blocks only. Nothing outside a domain/slice block is affected.

This styling is on by default and loads only when sphinx_structured_toc is in extensions. Set ulwazi_structured_toc_styling = False in conf.py to opt out and keep the extension’s own unstyled rendering instead. An invalid value for either separator-colour option is ignored (with a build warning) and the default takes over.

Note

If Ulwazi is selected only through html_theme (without "ulwazi" in extensions), these three values can’t be set with Sphinx’s -D command-line option – use conf.py instead. The same restriction already applies to notfound_enabled; see above.

MyST syntax defaults¶

Ulwazi does not install or activate MyST Markdown for you: add "myst_parser" to extensions yourself if you want Markdown sources. But when MyST is registered alongside "ulwazi", Ulwazi restores the syntax defaults that projects previously got from canonical-sphinx:

myst_enable_extensions = {"substitution", "deflist", "linkify"}

This applies only when myst_enable_extensions is unset in conf.py and on the command line. Explicit settings always replace the defaults – including an explicitly empty collection, which disables all optional syntax:

myst_enable_extensions = []  # no optional syntax at all

A custom collection is used as-is; the defaults are not merged in, so selecting one extension does not silently enable the others:

myst_enable_extensions = ["colon_fence"]  # only colon_fence

{{ key }} substitutions still need their values defined in myst_substitutions – Ulwazi only enables the syntax.

The linkify extension needs the linkify-it-py package, which myst-parser ships only through its optional linkify extra. Ulwazi depends on linkify-it-py directly, so a normal Ulwazi installation supplies it – you do not need to install the extra or add anything to your requirements.

Note

These MyST defaults require "ulwazi" in extensions. If Ulwazi is selected only through html_theme, its configuration hook never runs and MyST keeps its own empty default.

Note

Sphinx itself cannot convert a string -D myst_enable_extensions=... command-line override for this set-typed setting: it warns (cannot override config setting ... with unsupported type, ignoring) and keeps the conf.py value – with or without Ulwazi. Use the conf.py setting, or a typed override via Sphinx’s Python API (confoverrides={"myst_enable_extensions": [...]}), which Ulwazi honours.

HTML context¶

Sphinx makes values in the html_context dictionary available to HTML templates. Define this dictionary in conf.py; unlike top-level settings such as localtoc_max_depth, its values are grouped under html_context. Ulwazi uses them for theme elements such as navigation, feedback, and source links.

With defaults¶

Set these inside the html_context dictionary in conf.py, for example:

html_context = {
    "repo_branch": "main",
    "repo_folder": "/docs/",
}

If you don’t set them, Ulwazi uses the defaults below.

Setting	Default if unset	Purpose
`repo_branch`	`"main"`	Branch containing the doc source, used to build “edit this page” / “view source” links.
`repo_folder`	`"/docs/"`	Folder containing the doc source, used to build “edit this page” / “view source” links. Include the leading and trailing slashes when setting a custom folder.
`default_source_extension`	`".rst"`	Source file extension used to build “edit this page” / “view source” links on generated pages (such as `genindex`) without a source suffix. Set to `".md"` if your docs are written in MyST Markdown instead of reStructuredText.
`discourse`	`"https://discourse.ubuntu.com"`	Base URL for the Discourse link shown in the header’s community-links menu (only shown if this is set to a non-empty value).
`tag_id`	`"GTM-N384JMX2"`	Google Tag Manager container ID used by the analytics snippet included on HTML pages. Set your own container ID to replace Canonical’s default. Ulwazi has no setting to omit the snippet.
`footer`	See sub-keys below.	Dictionary controlling what appears in the page footer. Defaults are applied per key: a partially configured `footer` keeps its explicit values, and only the missing keys are filled in.
`footer.product`	`True`	Whether to add the product name as the footer’s first entry.
`footer.license`	`True`	Whether to add the license as the footer’s second entry (requires `license.name` to also be set).
`footer.entries`	`['<a href="#tracker-settings" class="js-revoke-cookie-manager muted-link">Manage your tracker settings</a>']`	List of raw HTML snippets appended to the footer. Accepts HTML tags.

Without defaults¶

These have no fallback value. Most are simply optional, and, if unset, the feature they control doesn’t render, and nothing breaks. A few are used without setting a value, so an incomplete setup can produce a broken link.

Setting	If unset	Purpose
`feedback`	Feedback/edit/view icons don’t render.	Set to `True` (or leave unset/`False`) to show or hide the feedback button and the “edit this page” / “view source” icons.
`github_url`	If `feedback` is `True` but `github_url` is unset, the feedback button still renders with a broken/incomplete link (`href="/issues/new?..."` with no host).	Documentation repository URL, used for the feedback button and to build edit/view links. Required for `feedback` to work correctly.
`default_edit_url` / `default_view_url`	Used as-is when `github_url` or the current page name isn’t available. If unset in that situation, the edit/view icons render with an empty link.	Fallback “edit this page” / “view source” URLs for pages that can’t build one from `github_url` + page name.
`mattermost`	Link doesn’t render.	Adds a Mattermost link to the header’s community-links menu.
`matrix`	Link doesn’t render.	Adds a Matrix link to the header’s community-links menu.
`product_page`	If unset or empty, the project-name link in the header points to the documentation root configured by Sphinx’s `root_doc` (normally `index`).	Product website hostname and optional path, without `https://` (e.g. `ubuntu.com/lxd`). When set, the project-name link points to `https://` plus this value instead of the documentation root.
`add_product_menu`	Product menu doesn’t render.	Set to `True` (or leave unset/`False`) to include or hide Canonical’s generated product menu at the top of every page.
`license`	No license shown (even if `footer.license` is `True`).	Dict with a `name` (e.g. an SPDX identifier like `"GPL-3.0-only"`) and optional `url`, shown in the footer.
`logo_link_URL`	If unset, the header logo links to an empty href.	Destination URL for the logo in the header navigation.
`logo_img_URL`	If unset, the header logo `<img>` has an empty `src`.	Image URL for the logo in the header navigation.
`logo_title`	If unset, the text label next to the header logo is empty.	Text label shown beside the logo in the header navigation.
`help_links`	“Get help” panel doesn’t render.	Dictionary rendering a “Get help” panel below the Global ToC in the side navigation, listing external help resources; see below.

Get help links¶

Set help_links in conf.py to render a “Get help” panel below the Global ToC in the side navigation, with links to resources outside your documentation tree (a forum, an issue tracker, a chat channel):

html_context = {
    "help_links": {
        "title": "Get help",
        "links": [
            {"text": "Ask on the forum", "url": "https://discourse.ubuntu.com"},
            {"text": "Report a doc issue", "url": "https://github.com/example/docs/issues/new"},
        ],
    },
}

The panel is off by default: leave help_links unset (or set it to False) and the side navigation is unchanged. title must be a non-empty string and links a non-empty list of {text, url} entries; each url must be an absolute http(s) URL. An invalid value is ignored as a whole (with a build warning naming the offending key) rather than rendering a partial panel.

Not currently supported¶

Ulwazi supplies defaults for these html_context values, but no Ulwazi template reads them yet. Setting them has no visible effect on the theme; the purposes below describe their intended or legacy use.

Setting	Default if unset	Intended purpose
`product_tag`	`"_static/tag.png"`	Product tag/logo image path.
`github_issues`	`"enabled"`	Toggle the GitHub issues integration.
`sequential_nav`	`"none"`	Control previous/next page navigation (documented values: `none`, `prev`, `next`, `both`).
`display_contributors`	`True`	Toggle a contributors list (`True`/`False`).
`path`	`"/docs"`	Reserved/legacy value.

Deprecated aliases¶

These older setting names (from the previous, Furo-based canonical-sphinx theme) are still honoured for backwards compatibility. If you set an old name without also setting its replacement, Ulwazi copies the value across and logs a deprecation warning at build time:

Deprecated name	Use instead
`github_version`	`repo_branch`
`github_folder`	`repo_folder`

If both the old and new names are set, the new name takes precedence and no warning is shown.