# Skill Toc Tree

> Qt documentation topic tree (TOC, navigation sidebar) — how a module's tree is declared via qhp subprojects, how manually written pages attach to it through the module's *-toc.qdoc page, and how module trees merge into the Qt Framework website tree via tree_config.xml. Load this skill when adding a manually written page, creating module docs from scratch, diagnosing a page missing from the sidebar or QCH contents, fixing page order, a wrong breadcrumb parent, or missing previous/next links, adding a whole group of pages to the tree via \generatelist, resolving toctitles/indexTitle warnings, or auditing a module for orphan pages.

- Skill: `qt/skill-toc-tree` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add qt/skill-toc-tree`
- Raw SKILL.md: https://api.skillmd.com/api/skills/qt/skill-toc-tree/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: qt (https://skillmd.com/u/qt)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/qt/skill-toc-tree

---


# Qt Documentation Topic Tree Reference

How Qt documentation pages become visible — and ordered — in the
navigation tree: the QCH contents in Qt Assistant/Qt Creator and the
sidebar on doc.qt.io.

## When to Use

- A new manually written page must appear in the tree
- Creating module documentation from scratch (new module)
- A page builds fine but is missing from the sidebar or QCH contents
- Pages appear in the wrong order or at the wrong nesting level
- Build log shows `Failed to find table of contents with title` or
  `Failed to find <P>.indexTitle`
- Auditing a module for orphan pages

## The Module Tree

A module's tree is declared by `qhp.<Module>.subprojects`. **Item order
is significant** — it is the order of the branches in the tree:

```
qhp.QtQuick.subprojects = manual examples qmltypes classes
```

puts the manually combined nodes first, then selector-generated
examples, then QML types, then the C++ API. Conventional branches —
modules use whichever subset applies:

| Branch | Subproject | Source of entries | Populated |
|--------|-----------|-------------------|-----------|
| Manual docs | `manual`, `type = manual` | `\list` on `<module>-toc.qdoc` | **by hand** |
| Examples | `examples`, `selectors = example` | `\example` nodes | automatic |
| C++ reference | `classes`, `selectors = class …` | `\class`/`\headerfile` | automatic |
| QML reference | `qmltypes`, `selectors = qmlclass` | `\qmltype` nodes | automatic |

**The rule this skill enforces:** selector-based branches are collected
automatically; manually written pages are not. A manually written page
is in the tree only if it is listed on `<module>-toc.qdoc`.

The tree visible in the QCH is the same tree that appears on the
website. Preview it locally by opening the compiled `.qch` in
Qt Creator's help viewer or in Qt Assistant.

**Small-module variant:** a module with one or two doc topics can skip
the `manual` branch and TOC page. A subproject whose `indexTitle` is
the one topic and whose selectors match nothing yields a single tree
entry (QtSpatialAudio: `subprojects.overview.indexTitle = Spatial Audio
Overview`, `selectors = group:none`; since QDoc 6.9 the documented form
is `selectors = none`).

For subproject properties and selectors, read
`references/qhp-subprojects.md`.

## Groups Are Lists, Not Navigation

`\group`, `\ingroup`, `\annotatedlist`, and `\generatelist` create
topic *listings* on pages. Group membership does **not** place a page
in the tree. The `\group` page itself, however, should be listed on the
module's TOC page like any other manually written page.

For group and list command syntax, read
`skill-qdoc/references/group-and-organization.md`.

## The Module Contract

Five qdocconf values must each match a `\title` exactly. Qt Quick
(`qtdeclarative/src/quick/doc/qtquick.qdocconf`) exercises all of them:

| qdocconf variable | Value (Qt Quick) | Must equal `\title` of |
|-------------------|------------------|------------------------|
| `navigation.landingpage` | `Qt Quick` | the landing page (`qtquick.qdoc`, `\page qtquick-index.html`) |
| `navigation.cppclassespage` | `Qt Quick C++ Classes` | the C++ classes page — usually the `\module` page, sometimes a plain `\page` |
| `navigation.qmltypespage` | `Qt Quick QML Types` | the `\qmlmodule` page |
| `navigation.toctitles` | `Qt Quick module topics` | the TOC page |
| `qhp.QtQuick.subprojects.manual.indexTitle` | `Qt Quick module topics` | the same TOC page |

The last two name the **same page**: one `\list` on `qtquick-toc.qdoc`
drives both the previous/next page order (`navigation.toctitles`) and
the `manual` branch of the tree (`indexTitle` + `type = manual`).

## The `<module>-toc.qdoc` Page

```qdoc
/*!
    \page qtquick-toc.html
    \title Qt Quick module topics

    \list
    \li \l {Getting started with Qt Quick applications}{Getting Started}
        \list
            \li \l {First Steps with QML}
        \endlist
    \li \l {Important Concepts In Qt Quick - The Visual Canvas}{Visual Canvas}
    \endlist
*/
```

- Nesting depth = tree depth; list order = page order (previous/next).
- Link by page `\title`; an optional second argument sets the visible
  tree label.
- **Tree items must be `\l` links (or a `\generatelist`).** A
  plain-text `\li` item is not displayed in the tree.
- Use `\generatelist [descending] <group>` (QDoc 6.11+) to add
  numerous homogeneous topics that need no subitems — linter
  diagnostics, what's new items. See `references/toc-page.md`.

For `navigation.toctitles` semantics and worked examples, read
`references/toc-page.md`.

## The Framework Tree

`qtdoc/doc/config/style/tree_config.xml` holds the root structure of
the **Qt Framework** documentation (not Qt Creator or other projects).
It specifies how the module trees are merged into the single tree on
the website: `<node toc="qtcore"/>` inserts a module's tree,
`parent_url` grafts it under another module's page, and
`<node title= href=>` creates folder nodes. The file carries a
comprehensive doc comment on its own format.

A module without a `manual` branch or TOC page still appears here —
its tree is just the selector-generated branches (many `<node toc=>`
entries have no matching `*-toc.qdoc`).

For the node format and the new-module procedure, read
`references/tree-config-xml.md`.

## Procedure A — Add a Manually Written Page

1. Locate the module's TOC page: the file whose `\title` matches
   `navigation.toctitles` (conventionally `<module>-toc.qdoc`).
2. Add an `\li \l {Page Title}` entry at the intended depth and
   position. Position sets previous/next order; depth sets nesting.
3. API and example pages need nothing — selectors collect them.
4. Rebuild; confirm no `Failed to find table of contents` warning and
   that the page appears in the `.qch` contents.

## Procedure B — Create Module Docs from Scratch

For **new modules only**. Two sides, two repositories:

1. Module side: landing page (`<module>-index.qdoc`), `\module` and/or
   `\qmlmodule` pages, the TOC page, the five matching qdocconf values
   (see The Module Contract), and `qhp.<Module>.subprojects` in tree
   order. Small modules may use the single-topic subproject instead.
2. qtdoc side: add a `<node toc="<module>"/>` entry to
   `qtdoc/doc/config/style/tree_config.xml`, with `parent_url` if the
   module belongs under another module's node.

Skipping step 2 produces no warning — the module simply never appears
in the website tree.

## Procedure C — Orphan Audit

A manually written page is in the tree **iff** it is reachable from the
module's TOC page. Group membership does not count.

1. Enumerate manually written pages:
   ```bash
   grep -rh "^[[:space:]]*\\\\page " src/<mod>/doc/src \
     --include="*.qdoc" | awk '{print $2}' | sort > /tmp/pages.txt
   ```
2. Collect their titles (a second grep for `\title` in the same
   files). Subtract auto-collected node types (`\example`, `\class`,
   `\qmltype` pages need no TOC entry) and every branch root: the
   landing page (`navigation.landingpage`), the TOC page itself, and
   **every `qhp.<P>.subprojects.*.indexTitle` value** — those pages
   are the roots of the selector branches, already in the tree.
3. Extract every `\l {Title}` from `<module>-toc.qdoc` (including
   nested lists) and compare.
4. Report each unlisted page as ORPHAN. Flag `\group` pages missing
   from the TOC page. QDoc itself never warns about orphans.

## Warning Catalogue

Exact strings to grep in build logs:

| Warning | Cause | Fix |
|---------|-------|-----|
| `Failed to find table of contents with title '<T>'` | `navigation.toctitles` names no page `\title` | Match the value to the TOC page title |
| `Failed to find <prefix>.indexTitle '<T>'` (`<prefix>` = full qdocconf path, e.g. `qhp.QtCore.subprojects.manual`) | Subproject `indexTitle` names no page | Match `indexTitle` to the page title |
| `'\generatelist <G>' no such group` | No entity has `\ingroup <G>` | Fix group name or add members |
| `'\generatelist <G>' group is empty` | Group exists, no matching items | Add members or drop the list |

## Silent Failures

No warning is emitted for any of these:

- Manually written page never added to the TOC page — builds clean,
  absent from every tree.
- A plain-text `\li` item (no `\l`) in the TOC list — silently
  omitted from the tree.
- Module missing from `tree_config.xml` — invisible on the website.
- A subproject defined but not listed in `qhp.<P>.subprojects` — the
  block is ignored (live example: qtdoc's `examples` block).
- `\generatelist` inside a TOC list on QDoc < 6.11 — no navigation
  links are generated for the group members.
- `\ingroup` consumes the rest of the line — a trailing comment
  silently becomes part of the group name.

## Reference Materials

| File | Content |
|------|---------|
| `references/toc-page.md` | TOC page anatomy, `navigation.toctitles`, `\generatelist` caveat, legacy nav commands |
| `references/qhp-subprojects.md` | `qhp.*` properties, selectors, branch order, single-topic pattern |
| `references/tree-config-xml.md` | Framework tree node format, merge order, new-module procedure |

## Owned Elsewhere — Do Not Duplicate

| Topic | Owner |
|-------|-------|
| `\group`/`\ingroup`/`\generatelist` syntax | `skill-qdoc/references/group-and-organization.md` |
| Landing page structure (R58), qdocconf (R61) | `skill-language-style/references/page-templates.md` |
| HTML output filename patterns | `skill-qdoc-output` |
| General qdocconf variables (`project`, `depends`, `imagedirs`, `warninglimit`) | `skill-qdoc/references/advanced-qdocconf.md` |

## External References

- [QDoc Manual: navigation](https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#navigation-variable)
- [QDoc Manual: Creating Help Project Files](https://doc.qt.io/qt-6/22-creating-help-project-files.html)

## Version History

- **1.0.0** (2026-08-14): Initial version — module tree subprojects,
  TOC page, framework tree, orphan audit