---
title: "Checking headline anchors"
manual: "Render guides"
version: "main"
permalink: "https://docs.typo3.org/permalink/t3renderguides:headlineanchorcheck"
source: "Developer/HeadlineAnchorCheck.rst"
rendered: "2026-09-24T12:21:12+00:00"
---

# Checking headline anchors {#headlineanchorcheck}

The documentation guidelines ask for an anchor on every headline, so that a
permalink can lead to it, see
[Link anchors](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Links/Anchors.html#link-anchor).
Only a label written before a headline registers such an anchor. The id the
rendering derives from the title works on the page alone, and changes when
the headline is reworded.

A manual can have the rendering warn about every headline without one:

**Documentation/guides.xml**

```xml
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
           interlink-shortcode="my-manual"
           check-headline-anchors="true"
/>
```

The warning names the headline and suggests a label made from it:

```text
The headline "Inline columns" has no anchor, so no permalink leads to it.
Give it one: ..  _inline-columns:
```

The check is off by default. Many manuals, and those of third-party
extensions most of all, still have headlines without a label, and a warning
fails a render with `--minimal-test`, which is what their pipelines run.

## What is checked {#what-is-checked}

Every headline, the page title included. A label counts when it stands before
the headline, with only blank lines or an `..  index::` directive between
them:

```rst
..  _inline-columns:

Inline columns
==============
```

Whether an anchor is used twice is not part of this check: the rendering
already warns about a duplicate anchor on its own.

A manual written in Markdown is never checked, even with the setting on. A
Markdown headline cannot carry a label, so nothing could fix the warning.

## Switching the check per page {#switching-the-check-per-page}

A page can override the manual's setting with a field at its top, before the
title:

```rst
:check-headline-anchors: off

=====
Title
=====
```

`:check-headline-anchors: on` works the other way, for a manual that is
being given its anchors page by page while the manual's setting is still off.

The check works the same way as the one for
[link texts](https://docs.typo3.org/permalink/t3renderguides:linktextcheck), and a manual can switch on either or both.