---
title: "Checking link texts"
manual: "Render guides"
version: "0.44"
permalink: "https://docs.typo3.org/permalink/t3renderguides:linktextcheck"
source: "Developer/LinkTextCheck.rst"
rendered: "2026-09-23T14:52:35+00:00"
---

# Checking link texts {#linktextcheck}

A reference written without a link text of its own shows the title of its
target. The documentation guidelines ask for a text of its own instead, see
[Link text](https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/Reference/ReStructuredText/Links/Documentation.html#link-text). A
manual can have the rendering warn about every reference that has none:

**Documentation/guides.xml**

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

The check is off by default. Most manuals still have references without a link
text, and a warning fails a render with `--minimal-test`, which is what
their pipelines run.

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

-   **`:ref:` and `:doc:`**

    Warns about `:ref:`my-label` and :rst:`:doc:`Some/Page`, but not
    about `:ref:`Link text \<my-label>\`\`.

-   **Permalinks**

    Warns about a permalink URL written on its own, such as
    `https://docs.typo3.org/permalink/my-manual:my-label`, since it too
    shows the title of its target.

Not checked are the roles that show the name they point to, such as
`:php:`, `:confval:` or `:t3ext:`, and the `:changelog:`
option of `versionchanged` and its kind, which shows the title of the
changelog entry by design.

The warning names the file, but not the line, since a reference does not
record where it was written.

## 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. This switches the check off for a page that shows a reference without
a link text on purpose:

**Documentation/Menus/NavigationTitle.rst**

```rst
:check-link-text: off

================
Navigation title
================
```

`:check-link-text: on` works the other way, for a manual that is being
cleaned up page by page while the manual's setting is still off.