netresearch/typo3-docs-skill / skills/typo3-docs
typo3-docs
FlaggedUse when TYPO3 extension documentation has to render on docs.typo3.org, which builds a manual from Documentation/guides.xml and reads no Settings.cfg (a single README.rst serves an extension too small for one): when an extension has no documentation yet, or when creating, editing or reviewing Documentation/*.rst, guides.xml, README.md or XLF translations, rendering docs with Docker, TYPO3 RST directives, screenshots, or XLIFF 2-space indentation (TYPO3 v14+).
references/guides-xml.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# guides.xml Configuration Reference
Working reference for `Documentation/guides.xml`, with labelled Netresearch
deltas. Canonical source (wins on conflict — see `canonical-sources.md`):
[guides.xml reference](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/GuidesXml.html)
## Overview
The `guides.xml` file configures documentation rendering, project metadata, GitHub integration, and cross-references. It replaces the legacy `Settings.cfg`.
## Extracting Information for guides.xml
When creating or updating `guides.xml`, extract information from these sources:
### From composer.json
```json
{
"name": "vendor/package-name",
"description": "Package description",
"license": "GPL-2.0-or-later",
"authors": [
{"name": "Company Name", "email": "info@example.com"}
],
"support": {
"issues": "https://github.com/vendor/repo/issues",
"source": "https://github.com/vendor/repo"
}
}
```
Extract:
- `name` → `interlink-shortcode` (e.g., `vendor/package-name`)
- `description` → Consider for `<project title="">`
- `authors[0].name` → `copyright`
- `support.issues` → `project-issues`
- `support.source` → `project-repository`
### From GitHub Repository
Use `gh` CLI to extract repository information:
```bash
# Get repository details
gh repo view --json name,owner,description,url
# Get default branch
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
# Get homepage if set
gh repo view --json homepageUrl --jq '.homepageUrl'
```
Extract:
- `owner.login` + `name` → `edit-on-github` (format: `owner/repo`)
- `defaultBranchRef.name` → `edit-on-github-branch`
- `url` → `project-repository`
- `homepageUrl` → `project-home` (if set)
### From Git Remote
```bash
# Extract owner/repo from git remote
git remote get-url origin | sed -E 's/.*[:/]([^/]+)\/([^/.]+)(\.git)?$/\1\/\2/'
```
## Complete guides.xml Template
```xml
<?xml version="1.0" encoding="UTF-8"?>
<guides
xmlns="https://www.phpdoc.org/guides"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
default-code-language="php"
links-are-relative="true"
>
<project
title="Extension Name"
version="1.0"
release="1.0.0"
copyright="since 2024 by Vendor Name"
/>
<extension
class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
typo3-core-preferred="stable"
interlink-shortcode="vendor/extension-name"
project-home="https://extensions.typo3.org/extension/extension_key"
project-contact="https://github.com/vendor/extension/issues"
project-repository="https://github.com/vendor/extension"
project-issues="https://github.com/vendor/extension/issues"
project-discussions="https://github.com/vendor/extension/discussions"
edit-on-github="vendor/extension"
edit-on-github-branch="main"
edit-on-github-directory="Documentation"
/>
<!-- Note: Only include project-discussions if GitHub Discussions is enabled -->
<!-- Intersphinx inventories for cross-references -->
<inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
<inventory id="t3tca" url="https://docs.typo3.org/m/typo3/reference-tca/main/en-us/"/>
<inventory id="t3tsconfig" url="https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/"/>
<inventory id="t3tsref" url="https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/"/>
</guides>
```
## Element Reference
### Root Element: `<guides>`
| Attribute | Type | Default | Description |
|-----------|------|---------|-------------|
| `default-code-language` | string | `php` | Default language for code blocks without explicit language |
| `links-are-relative` | boolean | `false` | Use relative links in output |
| `max-menu-depth` | integer | unlimited | Limit main menu nesting depth |
| `automatic-menu` | boolean | `false` | Auto-generate alphabetical menu (for Markdown docs) |
**The TYPO3 theme comes from `<extension class=…>`, not from a `theme`
attribute.** `[upstream]` The upstream reference documents no `theme` setting,
and the canonical projects (the manual's own `guides.xml`, `georgringer/news`,
`typo3/sysext/core`) omit it — the schema accepts a `theme` attribute, but do
not set it, and never add a `<theme>` child element (invalid per
`guides.xsd`). An earlier version of this file declared `theme="typo3docs"`
mandatory; that rule was skill-invented.
### `<project>` Element
Project metadata displayed in rendered documentation. Upstream marks all four
attributes optional; grading `title`/`copyright` as required is `[NR policy]`
(completeness bar).
| Attribute | Required | Description |
|-----------|----------|-------------|
| `title` | Yes (NR) | Extension/project name, displayed in sidebar and page title |
| `version` | No | Version number (auto-set during CI/CD, local only) |
| `release` | No | Release number, available via `\|release\|` substitution |
| `copyright` | Yes (NR) | Copyright statement for footer (e.g., "since 2024 by Company") |
**Extract from:**
- `title`: Extension name or `composer.json` description
- `copyright`: `composer.json` authors or company name
### `<extension>` Element
TYPO3-specific theme configuration. The `class` attribute loads the TYPO3 documentation theme which provides the official styling, "Edit on GitHub" buttons, version switcher, and intersphinx support.
| Attribute | Required | Description |
|-----------|----------|-------------|
| `class` | Yes | Always: `\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension` |
**Why `class` is required:** `[upstream]` since 2026-08-17 — the symptom (no error, the output just looks wrong) is now on the guides.xml reference. Without the theme extension class, documentation renders with default phpDocumentor styling instead of TYPO3's official theme. The class enables all TYPO3-specific features like the version switcher, intersphinx cross-references, and branded styling.
#### Required Attributes `[NR policy]`
The REQUIRED grading below is **Netresearch policy** (a completeness bar for
our extensions); upstream treats these as optional settings. The following
`<extension>` attributes are REQUIRED on every `guides.xml`. Omitting any of
these is a documentation defect.
| Attribute | Required | Description |
|-----------|----------|-------------|
| `project-home` | **REQUIRED** | Extension homepage (TER page or custom website) |
| `project-contact` | **REQUIRED** | GitHub Discussions or Issues URL. **NEVER** use `mailto:` |
| `project-repository` | **REQUIRED** | Source code URL (`https://github.com/vendor/repo`) |
| `project-issues` | **REQUIRED** | Issue tracker URL (`https://github.com/vendor/repo/issues`) |
| `project-discussions` | **REQUIRED if enabled** | GitHub Discussions URL (if Discussions is enabled on repo) |
| `edit-on-github` | **REQUIRED** | Format: `Organization/Repository` |
| `edit-on-github-branch` | **REQUIRED** | Default branch name (e.g., `main`) |
| `edit-on-github-directory` | **REQUIRED** | Path to Documentation/ within repo (typically `Documentation`) |
**NEVER use `mailto:` for `project-contact`.** `[NR policy]` Upstream
explicitly allows an email address here — `mailto:documentation@typo3.org` is
the documented example — but Netresearch forbids email addresses in public
documentation (spam, PII). Use a GitHub Issues or Discussions URL instead. Do
not present this as a TYPO3 rule.
**Extract from:** Git remote URL, `gh repo view`, or `composer.json` support section
#### Project Links Details
| Attribute | Description | Example |
|-----------|-------------|---------|
| `project-home` | Extension homepage | TER page or custom website |
| `project-contact` | Contact for questions | GitHub Issues or Discussions URL (**NEVER** `mailto:` — `[NR policy]`, upstream allows it) |
| `project-repository` | Source code URL | `https://github.com/vendor/repo` |
| `project-issues` | Issue tracker URL | `https://github.com/vendor/repo/issues` |
| `project-discussions` | Discussions forum | GitHub Discussions URL (REQUIRED if enabled on repo) |
| `report-issue` | Override issue link | `none`, internal path, or URL (upstream default: value of `project-issues`) |
Upstream defaults worth knowing: `edit-on-github-branch` defaults to `main`,
`edit-on-github-directory` to `Documentation` — setting them explicitly is
documentation, not necessity.
**project-discussions:** Add this attribute if GitHub Discussions is enabled on the repository. Check with:
```bash
gh repo view --json hasDiscussionsEnabled --jq '.hasDiscussionsEnabled'
# If true, add:
gh repo view --json url --jq '"\(.url)/discussions"'
```
**report-issue:** Controls the "Report Issue" button behavior:
- **Omit attribute**: Uses `project-issues` URL (default behavior)
- **`none`**: Hides the "Report Issue" button entirely (use for internal/private docs)
- **URL**: Custom URL for issue reporting (e.g., different tracker, form)
- **Internal path**: Link to a documentation page (e.g., `/Contribute/ReportIssue`)
#### Interlink Configuration
| Attribute | Description |
|-----------|-------------|
| `interlink-shortcode` | Identifier for "Reference this headline" dialog |
| `typo3-core-preferred` | Target TYPO3 version for cross-manual links |
**interlink-shortcode values:**
- Third-party extensions: Use Composer name (e.g., `georgringer/news`)
- System extensions: Use Composer name (e.g., `typo3/cms-adminpanel`)
**typo3-core-preferred values:**
- `main` - Development version
- `stable` - Latest LTS (default)
- `oldstable` - Previous LTS
- Explicit version: `12.4`, `11.5`, `8.7`
### `<inventory>` Elements
`<inventory id="…" url="…"/>` defines an Intersphinx inventory for
cross-references; both attributes are required — syntax and semantics:
[guides.xml reference](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/GuidesXml.html)
`[upstream]`. The URL must end with `/` (see Common Mistakes).
#### When to Add Inventories
Add an `<inventory>` element **only when your documentation uses cross-references to that manual**. Do not add unused inventories.
**Detection:** Search your RST files for `:ref:` patterns with prefixes:
```bash
grep -rE ':ref:`t3[a-z]+:' Documentation/
```
If you use `:ref:`t3coreapi:dependency-injection``, add the `t3coreapi` inventory.
#### Common Inventories
```xml
<!-- Core references -->
<inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
<inventory id="t3tca" url="https://docs.typo3.org/m/typo3/reference-tca/main/en-us/"/>
<inventory id="t3tsconfig" url="https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/"/>
<inventory id="t3tsref" url="https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/"/>
<!-- Guides -->
<inventory id="t3start" url="https://docs.typo3.org/m/typo3/tutorial-getting-started/main/en-us/"/>
<inventory id="t3editors" url="https://docs.typo3.org/m/typo3/tutorial-editors/main/en-us/"/>
<!-- ViewHelper reference -->
<inventory id="t3viewhelper" url="https://docs.typo3.org/other/typo3/view-helper-reference/main/en-us/"/>
<!-- Extbase/Fluid -->
<inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/main/en-us/"/>
```
**Usage in RST:**
```rst
See :ref:`t3coreapi:dependency-injection` for details.
See :ref:`t3tca:columns-types` for TCA column types.
```
## Automated guides.xml Generation
When creating `guides.xml` for an extension, follow this workflow:
### Step 1: Extract from composer.json
```bash
# Read composer.json
cat composer.json | jq -r '.name' # → interlink-shortcode
cat composer.json | jq -r '.authors[0].name' # → copyright
cat composer.json | jq -r '.support.issues' # → project-issues
cat composer.json | jq -r '.support.source' # → project-repository
```
### Step 2: Extract from GitHub
```bash
# Get owner/repo for edit-on-github
gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'
# Get default branch
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
# Get issues URL
gh repo view --json url --jq '"\(.url)/issues"'
# Check if Discussions enabled (add project-discussions only if true)
gh repo view --json hasDiscussionsEnabled --jq '.hasDiscussionsEnabled'
# If true:
gh repo view --json url --jq '"\(.url)/discussions"'
```
### Step 3: Determine Extension Key
The extension key (for TER link) is typically:
- Composer name without vendor: `vendor/my-extension` → `my_extension`
- Or explicitly defined in `composer.json` extras
### Step 4: Generate guides.xml
Combine extracted values into the complete template above.
## Validation Checklist
Before committing `guides.xml`:
1. ✅ No `theme` attribute/element — the TYPO3 theme comes from `<extension class>`
2. ✅ `<extension class="...">` includes the required theme extension class
3. ✅ `<project title="">` is set with meaningful extension name
4. ✅ `<project copyright="">` includes year and author/company
5. ✅ `edit-on-github` matches GitHub `owner/repo` exactly
6. ✅ `edit-on-github-branch` matches your default branch
7. ✅ `project-repository` and `project-issues` are valid URLs
8. ✅ `project-discussions` added only if GitHub Discussions is enabled
9. ✅ `interlink-shortcode` uses Composer package name format
10. ✅ `typo3-core-preferred` set appropriately (stable, main, or specific version)
11. ✅ `<inventory>` elements added only for cross-references actually used
12. ✅ All inventory URLs end with `/`
13. ✅ `edit-on-github-directory` is set (typically `Documentation`)
14. ✅ `project-contact` uses a GitHub URL, **NEVER** `mailto:` (`[NR policy]`)
15. ✅ No `mailto:` links anywhere in `guides.xml` (`[NR policy]`)
## Common Mistakes
### Expecting a `theme` Setting
```xml
<!-- ❌ WRONG: a <theme> child element is invalid per guides.xsd -->
<guides>
<theme name="typo3docs"/>
</guides>
<!-- ✅ CORRECT: the TYPO3 theme is loaded by the extension class -->
<guides>
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"/>
</guides>
```
### Missing Extension Class
```xml
<!-- ❌ WRONG: missing class attribute -->
<extension
edit-on-github="vendor/repo"
/>
<!-- ✅ CORRECT: class is required -->
<extension
class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
edit-on-github="vendor/repo"
/>
```
### Wrong edit-on-github Format
```xml
<!-- ❌ WRONG: full URL -->
<extension edit-on-github="https://github.com/vendor/repo"/>
<!-- ❌ WRONG: missing owner -->
<extension edit-on-github="repo"/>
<!-- ✅ CORRECT: owner/repo format -->
<extension edit-on-github="vendor/repo"/>
```
### Inventory URL Missing Trailing Slash
`[upstream]` since 2026-08-17, stated on the [guides.xml
reference](https://docs.typo3.org/permalink/h2document:guides-xml) together
with the missing-`class` symptom below.
```xml
<!-- ❌ WRONG: no trailing slash -->
<inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us"/>
<!-- ✅ CORRECT: with trailing slash -->
<inventory id="t3coreapi" url="https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/"/>
```
## Minimal Valid guides.xml
For quick setup, use this minimal valid configuration:
```xml
<?xml version="1.0" encoding="UTF-8"?>
<guides
xmlns="https://www.phpdoc.org/guides"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
>
<project
title="My Extension"
copyright="since 2024 by My Company"
/>
<extension
class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
/>
</guides>
```
## References
- **guides.xml Reference:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/GuidesXml.html
- **Intersphinx / interlinks:** https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Links/Documentation.html#intersphinx
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |