---
title: "Configuration of the rendering - guides.xml"
manual: "How to Document"
version: "main"
permalink: "https://docs.typo3.org/permalink/h2document:guides-xml"
source: "Reference/GuidesXml.rst"
rendered: "2026-09-23T16:57:04+00:00"
---

# Configuration of the rendering - `guides.xml` {#guides-xml}

This XML file contains meta information and configuration used during rendering
of a manual.

**Documentation/guides.xml**

```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"
        links-are-relative="true"
        default-code-language="php"
>
    <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               project-home="https://extensions.typo3.org/extension/news/"
               project-contact="https://typo3.slack.com/archives/C03TG7QJT"
               project-repository="https://github.com/georgringer/news"
               project-issues="https://github.com/georgringer/news/issues"
               project-discussions="https://github.com/georgringer/news/discussions"
               edit-on-github-branch="main"
               edit-on-github="georgringer/news"
               typo3-core-preferred="11.5"
               interlink-shortcode="georgringer/news"
    />
    <project title="News system"
             version="local"
             copyright="since 2010 by Georg Ringer &amp; Contributors"
    />
    <inventory id="t3extbasebook" url="https://docs.typo3.org/m/typo3/book-extbasefluid/10.4/en-us/"/>
</guides>

```

**Table of Contents:**

-   [Init new guides.xml](https://docs.typo3.org/permalink/h2document:init-new-guides-xml)
-   [guides.xml API](https://docs.typo3.org/permalink/h2document:guides-xml-api-1)

## Init new `guides.xml` {#guides-xml-init}

If you start a new documentation guide, for example in a TYPO3 extension, use the
`init` command:

**Execute in extension root, the directory that contains your extension's composer.json**

```bash
docker run --rm --pull always -v $(pwd):/project -it ghcr.io/typo3-documentation/render-guides:latest init
```

And follow the interactive question.

> [!TIP]
> **Hint**
>
> If you are migrating from the legacy Sphinx-based rendering and still have
> a `Documentation/Settings.cfg` you can use an automatic migration
> tool to [migrate the Settings.cfg into a guides.xml](https://docs.typo3.org/permalink/h2document:migrate-guides-xml)

## `guides.xml` API {#guides-xml-api}

-   **\<guides>**

    The `<guides>` tag is the root tag of the `Documentation/guides.xml`.
    It is used for general configuration during parsing and rendering.

    The following settings can be relevant for TYPO3 themed documentation:

    > [!NOTE]
    > The schema accepts a `theme` attribute on `<guides>`,
    > but TYPO3 documentation does not need it: the theme is loaded by
    > the `<extension class="...Typo3DocsThemeExtension">` tag. A
    > `<theme>` **child element** is invalid and aborts rendering
    > with `Invalid type for path guides.theme`.

    -   **default-code-language**

        -   *Type:* string

        Can be used to set the code-language that should be used for
        [code-blocks](https://docs.typo3.org/permalink/h2document:codeblock-directive) if no language is set.

        We advice to set the language to be used in each code-block however.

    **Example: Use `typoscript` as default language for code-blocks**

    **EXT:my_extension/Documentation/guides.xml (excerpt)**

    ```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="typoscript"
    >
        <!-- [...] -->
    </guides>
    ```

    -   **max-menu-depth**

        -   *Type:* integer
        -   *Default:* `PHP_INT_MAX`

        Limits the main menu to a certain amount of levels. As level creation is
        one of the main bottle-necks that can slow down rendering it can be helpful
        to limit the levels in the menu in some use cases.

    **Example: Limit the menu to 2 levels**

    The changelog (documentation of the extension "core") consists of several thousands of
    pages. The reason is that very long lists of changelog entries in the menu are not helpful to
    the user and slow down the search.

    **EXT:core/Documentation/guides.xml (excerpt)**

    ```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"
            max-menu-depth="2"
    >
        <!-- [...] -->
    </guides>
    ```

    -   **automatic-menu**

        -   *Type:* boolean
        -   *Default:* `false`

        If this option is set to true, an [alphabetical menu is
        automatically created](https://docs.typo3.org/permalink/h2document:menu-automatic).

-   **\<inventory>**

    The `<inventory>` tag is located directly in the [guides tag](https://docs.typo3.org/permalink/h2document:settings-guides).
    There can be 0 or more `<inventory>` tags, each defines one Interlink
    inventory.

    A list of globally available Interlink (formerly "Intersphinx") repositories
    can be found in [Available default inventories](https://docs.typo3.org/other/t3docs/render-guides/main/en-us/Developer/InterlinkInventories.html#available-default-inventories)

    It is possible, though rarely needed to define custom interlink mappings:

    For example:

    **Documentation/guides.xml, excerpt**

    ```xml
    <inventory id="sphinx" url="https://www.sphinx-doc.org/en/master/"/>
    ```

    The `url` should end with a trailing slash (`.../en-us/`) —
    without it, resolving the inventory can fail.

-   **\<project>**

    The `<project>` tag is located directly in the [guides tag](https://docs.typo3.org/permalink/h2document:settings-guides).
    There can be 0 or 1 tag of that name.

    This tag can contain the following meta information:

    -   **title**

        -   *Type:* string

        The *project* tag contains the title of the project and is displayed in the
        left sidebar (desktop) or the top (mobile) of the theme and in the title meta
        tag.

        For TYPO3 extensions we suggest to use the extension name in a readable
        format:

        -   Import / Export tool
        -   News
        -   Mask

        Common values are in the official TYPO3 manuals

        1.  `<Topic> Guide`, e.g. "Frontend Localization Guide",
            for collections of articles on a specific topic
        1.  `<Topic> Reference`, e.g. "TSconfig Reference",
            for a complete reference
        1.  `<Topic> Tutorial`, e.g. "Editors Tutorial",
            for collections of tutorials on a specific topic

    **Example: Set the title of a project, including version, release and copyright**

    **EXT:news/Documentation/guides.xml (excerpt)**

    ```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="News system"
                 version="local"
                 copyright="since 2010 by Georg Ringer &amp; Contributors"
        />
    </guides>
    ```

    -   **version**

        -   *Type:* string

        When documentation is rendered in the GitHub action for deployment onto
        [https://docs.typo3.org](https://docs.typo3.org) **the version is set automatically** to the extension's
        version derived from the Git tag. Setting the version in the
        `guides.xml` only affects local rendering.

    -   **release**

        -   *Type:* string

        You can set the `release` property to the release number of your
        document and output this value using `|release|` within
        your text if you desire to. Usually it is not used.

    -   **copyright**

        -   *Type:* string

        The *copyright* attribute contains the copyright claim of the project. It is
        displayed in the footer as "© Copyright \<copyright>" and has in most use cases
        in the TYPO3 world the values:

        1.  `since <creation-year> by the TYPO3 contributors`,
            for example "since 1999 by the TYPO3 contributors" (official TYPO3 manuals and TYPO3
            system extensions)
        1.  `since <creation-year> by <vendor> & contributors`,
            for example "since 1999 by John Doe & contributors" (third-party TYPO3 extensions)

-   **\<extension>**

    The `<extension>` tag is located directly in the [guides tag](https://docs.typo3.org/permalink/h2document:settings-guides).

    TYPO3 Theme specific settings can be made in the tag
    `<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension">`.

    There can be 0 or more tags of that name, however only one `<extension>` tag
    should be defined for the TYPO3 documentation theme.

    The class attribute is mandatory, it references the extension that is used
    to render the documentation with the TYPO3 documentation theme.

    > [!NOTE]
    > If the `class` attribute (or the whole `<extension>`
    > tag) is missing, the documentation renders with the default
    > phpDocumentor layout instead of the TYPO3 theme. No error is
    > raised — the output just looks wrong.

    -   **edit-on-github-\***

        The *github_repository* and *github_branch* attributes should be set to provide
        the "Edit on GitHub" button, which allows the reader to jump from the currently
        viewed documentation directly to the associated GitHub repository and edit the
        page file.

        If the project is hosted on GitHub and public contributions are welcome, these
        attributes should be set accordingly:

        1.  `<user>/<repository>`, for example to "TYPO3-Documentation/TYPO3CMS-Reference-TCA"
            or "FriendsOfTYPO3/extension_builder".
        1.  `<branch>`, for example on "main" or "10.x".

        For example:

        **Documentation/guides.xml, excerpt**

        ```xml
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   edit-on-github-branch="main"
                   edit-on-github="TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument"
        />
        ```

    -   **edit-on-github**

        -   *Type:* string
        -   *Sytanx:* \[GitHub Organiziation or user\]/\[Repository\]
        -   *Default:* `""`

        If this configuration is set, a button "Edit on GitHub" is displayed on each
        page of the manual.

    **Example: Display a button to edit in the repository of news**

    **EXT:news/Documentation/guides.xml (excerpt)**

    ```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"
    >
          <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               edit-on-github-branch="main"
               edit-on-github="georgringer/news"
    />
    </guides>
    ```

    -   **edit-on-github-branch**

        -   *Type:* string
        -   *Default:* `main`

        The branch that should be used for the "Edit on GitHub" button.

    **Example: Display a button to edit in the repository of tt_news on branch master**

    **EXT:news/Documentation/guides.xml (excerpt)**

    ```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"
    >
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   edit-on-github-branch="master"
                   edit-on-github="FriendsOfTYPO3/tt_address"
        />
    </guides>
    ```

    -   **edit-on-github-directory**

        -   *Type:* string
        -   *Default:* `Documentation`

        The directory in which the documentation can be found. The GitHub render
        action currently does not support using other directories
        then `Documentation/`.

        This setting is used exclusively for system extension manuals as the TYPO3
        Core is kept in a mono repository on GitHub.

    **Example: Set the GitHub directory for a system extension**

    **EXT:adminpanel/Documentation/guides.xml (excerpt)**

    ```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"
    >
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   edit-on-github-branch="main"
                   edit-on-github="typo3/typo3"
                   edit-on-github-directory="typo3/sysext/adminpanel/Documentation/"
        />
    </guides>
    ```

    -   **interlink-shortcode**

        -   *Type:* string
        -   *Default:* `somemanual`

        The interlink shortcode will be displayed in the "Reference this headline"
        dialog when users click on the link symbol beside a headline or other
        linkable element.

        These references can be used to link to your manual from other documents
        rendered with the TYPO3 theme. However they will only work if you follow
        these rules:

        -   TYPO3 third-party extensions: Composer name, example: `georgringer/news`
        -   System extensions: Composer name, example: `typo3/cms-adminpanel`
        -   A shortcode supported by the theme:
            [Available default inventories](https://docs.typo3.org/other/t3docs/render-guides/main/en-us/Developer/InterlinkInventories.html#available-default-inventories)

    ![Reference a headline dialog showing the shortcode georgringer/news](../_Images/ReferenceThisHeadlineDialog.png)

    -   **project-\***

        The *project-\<topic>* attributes provide all links with the name "\<Topic>" in
        the footer of the documentation that guide the user to other aspects of the
        project than the documentation, for example to the project page in the
        TYPO3 Extension Repository (TER):

    -   **project-home**

        -   *Type:* string

        is set to the homepage URL of the project. For official TYPO3
        manuals this is the public base URL at docs.typo3.org, for public TYPO3
        extensions this is the associated TER page or a custom project website, for
        example

        -   `https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/` or
        -   `https://extensions.typo3.org/extension/news`.

    -   **project-contact**

        -   *Type:* string

        is usually set to an email address or Slack channel URL of
        the team behind the project, for example

        -   `mailto:documentation@typo3.org` or
        -   `https://typo3.slack.com/archives/C028JEPJL`.

    -   **project-repository**

        -   *Type:* string

        is set to the repository of the project's VCS, for
        example

        -   `https://github.com/FriendsOfTYPO3/extension_builder`.

    -   **project-issues**

        -   *Type:* string

        is set to the location where project issues are to be
        created and edited, for example

        -   `https://github.com/FriendsOfTYPO3/extension_builder/issues`

    -   **project-discussions**

        -   *Type:* string

        is used in the rare case that project-related
        discussions take place in locations other than those defined by the
        project-contact and project-issues attributes, for example

        -   `https://github.com/FriendsOfTYPO3/extension_builder/discussions`.

    **Example: Project links for a third-party extension**

    **EXT:news/Documentation/guides.xml (excerpt)**

    ```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"
    >
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               project-home="https://extensions.typo3.org/extension/news/"
               project-contact="https://typo3.slack.com/archives/C03TG7QJT"
               project-repository="https://github.com/georgringer/news"
               project-issues="https://github.com/georgringer/news/issues"
    />
    </guides>
    ```

    **Example: Project links for a system extension**

    **EXT:adminpanel/Documentation/guides.xml (excerpt)**

    ```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"
        >
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   project-home="https://extensions.typo3.org/extension/adminpanel/"
                   project-contact="https://typo3.slack.com/archives/C025BQLFA"
                   project-repository="https://github.com/typo3/typo3"
                   project-issues="https://forge.typo3.org/projects/typo3cms-core/issues"
        />
    </guides>
    ```

    **Example: Project links for a reference or guide**

    **Reference-TSconfig Documentation/guides.xml (excerpt)**

    ```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"
         >
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   project-home="https://docs.typo3.org/m/typo3/reference-tsconfig/main/en-us/"
                   project-contact="https://typo3.slack.com/archives/C028JEPJL"
                   project-repository="https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig"
                   project-issues="https://github.com/TYPO3-Documentation/TYPO3CMS-Reference-TSconfig/issues"
        />
    </guides>
    ```

    -   **report-issue**

        -   *Type:* string
        -   *Default:* value of [project-issues](https://docs.typo3.org/permalink/h2document:confval-guides-extension-project-issues)

        -   **`none`**

            Disable the "Report issue" button

        -   **`/SomePath/MyIssueReport`**

            Link to this page in your documentation.

        -   **`https://github.com/MyVendor/MyProject/issues/new`**

            Open issue on GitHub

        -   **`https://gitlab.com/myvendor/myproject/-/issues/new`**

            Open issue on GitLab

        -   **`https://forge.typo3.org/projects/typo3cms-core/issues/new`**

            Open issue on Forge (System extensions only)

        For security reasons arbitrary URLs are not allowed. If you use
        a private Gitlab or another issue tool, Make an internal page and
        link it like `/SomePath/MyIssueReport`.

    -   **typo3-core-preferred**

        -   *Type:* string
        -   *Default:* `stable`

        You can set the preferred TYPO3 Core version. This version is used to determine
        the desired version for links to other manuals and system extensions.

        **Documentation/guides.xml**

        ```xml
        <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
                   typo3-core-preferred="stable" />
        ```

        If no preferred version is set it defaults to `stable`. Possible values are:

        `main`, `stable` (latest LTS), `oldstable` (old LTS) or an explicit LTS / eLTS
        version like `12.4` or `8.7`.

    **Example: Set the preferred TYPO3 Core version to 11.5**

    At the time of writing the extension [EXT:news](https://extensions.typo3.org/extension/news) is compatible with TYPO3 v11.5
    and v12.4. When [referencing](https://docs.typo3.org/permalink/h2document:rest-cheat-sheet-links) Core manuals or
    extensions, we want the links to go automatically to version 11.5 of that
    reference or core extension. Therefore we set the preferred TYPO3 Core version
    to that value:

    **EXT:news/Documentation/guides.xml (excerpt)**

    ```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"
    >
         <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               typo3-core-preferred="11.5"
    </guides>
    ```

    **Example: Always link to the latest stable TYPO3 version**

    If you want your links to always go to the latest stable long time support version
    (LTS) of the TYPO3 Core, you can set [typo3-core-preferred](https://docs.typo3.org/permalink/h2document:confval-guides-extension-typo3-core-preferred) to stable.

    At the time of writing references to official manuals and Core extensions will
    be rendered to version 12.4. Once TYPO3 13 LTS is released they will automatically
    switch to the according version on next re-rendering.

    **EXT:my_extension/Documentation/guides.xml (excerpt)**

    ```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"
    >
         <extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
               typo3-core-preferred="stable"
    </guides>
    ```

    -   **check-link-text**

        -   *Type:* boolean
        -   *Default:* `false`

        Warn about every reference that has no link text of its own, see
        [Always give a link text](https://docs.typo3.org/permalink/h2document:link-text).
        A reference without one shows the title of its target, which rarely
        fits the sentence around it and changes when that title is renamed.

        **Documentation/guides.xml**

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

        The check warns about `:ref:`my-label`` and
        `:doc:`Some/Page``, and about a permalink URL written on its
        own, which shows the title of its target as well. It does not warn
        about roles that show the name they point to, such as
        `:php:`, `:confval:` or `:t3ext:`, nor about the
        `:changelog:` option of `versionadded` and its kind.

        A warning fails a render with `--minimal-test`, which is what
        the documentation pipeline runs, so switch the check on once the
        references of your manual have a link text. The warning names the
        file but not the line: a reference does not record where it was
        written.

        A single page can override the setting with the
        [check-link-text page field](https://docs.typo3.org/permalink/h2document:check-link-text-page).