# Skill Qdoc Output

> Reference for QDoc HTML output filename generation patterns by node type

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

---


# QDoc Output Filename Generation

How QDoc generates HTML filenames for different documentation node types.

## Source Code Reference

**Primary implementation:** `qttools/src/qdoc/qdoc/src/qdoc/generator.cpp`

| Function | Lines | Purpose |
|----------|-------|---------|
| `Generator::fileBase()` | 308-376 | Generates base filename without extension |
| `Generator::fileName()` | 418-438 | Adds file extension to base |
| `Generator::outputPrefix()` | 2103-2117 | Returns prefix by genus (e.g., "qml-") |
| `Generator::outputSuffix()` | 2119-2132 | Returns suffix by node type |

**Supporting code:**
- `Utilities::asAsciiPrintable()` - `utilities.cpp:157-197` - Canonicalizes to lowercase ASCII

## Filename Patterns by Node Type

| Node Type | Pattern | Example |
|-----------|---------|---------|
| C++ class | `{classname}.html` | `qwidget.html` |
| C++ class (namespaced) | `{namespace}-{class}.html` | `qt-alignment.html` |
| QML type | `qml-{module}-{type}.html` | `qml-qtquick-rectangle.html` |
| QML value type | `qml-{type}.html` | `qml-color.html` |
| C++ module | `{module}-module.html` | `qtcore-module.html` |
| QML module | `{module}-qmlmodule.html` | `qtquick-qmlmodule.html` |
| Group | `{groupname}.html` | `animation.html` |
| Example | `{project}-{name}-example.html` | `qtbase-calculator-example.html` |
| Page (overviews) | per `\page` command in source | `getting-started.html` |

**Important:** For `\page` documents, the HTML filename is explicitly specified in the source file's `\page` command. Always read the source to verify. For all other types (class, QML type, module, group, example), QDoc generates the filename automatically - verify via index files.

## Algorithm Detail

### fileBase() Logic (generator.cpp:308-376)

```
1. If CollectionNode:
   - If QmlModule: append "-qmlmodule"
   - Else if Module: append "-module"
   - Else (Group): no suffix
   - Append outputSuffix()

2. If TextPageNode:
   - If Example: prepend "{project}-", append "-example"

3. If QmlType:
   - If has logicalModuleName and not QmlBasicType:
     - Prepend "{logicalModuleName}{outputSuffix}-"
   - Prepend outputPrefix() (default: "qml-")

4. If ProxyNode:
   - Append "-{moduleName}-proxy"

5. Else (C++ class/namespace):
   - Build from parent chain with hyphens
   - For undocumented-here namespaces: append "-sub-{moduleName}"
   - Append outputSuffix()

6. Prepend outputPrefix()
7. Canonicalize with asAsciiPrintable()
```

### Canonicalization (utilities.cpp:157-197)

The `asAsciiPrintable()` function:
- Converts uppercase to lowercase
- Keeps alphanumerics and hyphens
- Replaces other characters with hyphens
- Adds MD5 hash suffix for non-ASCII content

## Index File Verification

HTML filenames can be verified in QDoc index files:

```bash
# Find class
grep 'class name="QWidget"' */doc/*/*.index
# Output: <class name="QWidget" href="qwidget.html" ...>

# Find QML type
grep 'qmlclass name="Rectangle"' */doc/*/*.index
# Output: <qmlclass name="Rectangle" href="qml-qtquick-rectangle.html" ...>

# Find group
grep '<group name="animation"' */doc/*/*.index
# Output: <group name="animation" href="animation.html" ...>

# Find module
grep '<module name="QtCore"' */doc/*/*.index
# Output: <module name="QtCore" href="qtcore-module.html" ...>
```

## Configuration

Prefixes and suffixes are configurable in qdocconf:

```
outputPrefixes = QML
outputPrefixes.QML = qml-

outputSuffixes = QML
outputSuffixes.QML =
```

**Defaults:**
- QML genus: prefix "qml-", no suffix
- CPP genus: no prefix, no suffix

## Common Patterns

### QML Type in Module

```
Input:  \qmltype Rectangle
        \inqmlmodule QtQuick

Output: qml-qtquick-rectangle.html
```

**Algorithm:**
1. Start with "rectangle" (lowercased)
2. Prepend "qtquick-" (logical module name)
3. Prepend "qml-" (output prefix)
4. Result: "qml-qtquick-rectangle"

### C++ Class in Namespace

```
Input:  \class Qt::Alignment

Output: qt-alignment.html
```

**Algorithm:**
1. Build chain: "Qt" + "-" + "Alignment"
2. Lowercase: "qt-alignment"
3. Result: "qt-alignment"

### Group Page

```
Input:  \group animation
        \title Animation Framework

Output: animation.html
```

**Algorithm:**
1. Start with "animation" (group name)
2. No suffix (not Module or QmlModule)
3. Result: "animation"

## Integration

- **skill-doc-diff:** Uses HTML filename patterns for the HTML field
- **skill-qdoc:** QDoc node system and link resolution context

## Version History

- **v1.0** (2026-02-11): Initial version
  - Documented fileBase() algorithm from generator.cpp
  - Added patterns for all node types including Group
  - Added index file verification examples