Configuration of the rendering - guides.xml

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

Example:
Documentation/guides.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>
Copied!

Table of Contents:

<guides>

<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:

default-code-language

default-code-language
Type
string

Can be used to set the code-language that should be used for code-blocks 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 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>
Copied!

max-menu-depth

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 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>
Copied!

<inventory>

<inventory>

The <inventory> tag is located directly in the guides tag. 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

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

For example:

Documentation/guides.xml, excerpt
<inventory id="sphinx" url="https://www.sphinx-doc.org/en/master/"/>
Copied!

<project>

<project>

The <project> tag is located directly in the guides tag. There can be 0 or 1 tag of that name.

This tag can contain the following meta information:

title

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
  2. <Topic> Reference, e.g. "TSconfig Reference", for a complete reference
  3. <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 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>
Copied!

version

version
Type
string

When documentation is rendered in the GitHub action for deployment onto 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

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)
  2. since <creation-year> by <vendor> & contributors, for example "since 1999 by John Doe & contributors" (third-party TYPO3 extensions)

<extension>

<extension>

The <extension> tag is located directly in the guides tag.

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.

edit-on-github-*

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".
  2. <branch>, for example on "main" or "10.x".

For example:

Documentation/guides.xml, excerpt
<extension class="\T3Docs\Typo3DocsTheme\DependencyInjection\Typo3DocsThemeExtension"
           edit-on-github-branch="main"
           edit-on-github="TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument"
/>
Copied!

edit-on-github

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 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>
Copied!

edit-on-github-branch

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 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>
Copied!

edit-on-github-directory

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 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>
Copied!

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
Reference a headline dialog showing the shortcode georgringer/news

Reference a headline in the EXT:news manual

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

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

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

project_repository
Type
string

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

  • https://github.com/FriendsOfTYPO3/extension_builder.

project_issues

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

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 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>
Copied!
Example: Project links for a system extension
EXT:adminpanel/Documentation/guides.xml (excerpt)
<?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>
Copied!
Example: Project links for a reference or guide
Reference-TSconfig Documentation/guides.xml (excerpt)
<?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>
Copied!

report_issue

report_issue
Type
string
Default
value of 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

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

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 is compatible with TYPO3 v11.5 and v12.4. When referencing 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 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>
Copied!
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 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 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>
Copied!