Migrate Documentation

Since May 29th 2019 a new infrastructure is in place at docs.typo3.org. This requires some migration tasks, in order to ensure that extension documentation is rendered on docs.typo3.org

Necessary Steps

The necessary steps are:

  1. Add mandatory composer.json, see composer.json

    This file is necessary, in order to determine required information, like vendor, package name and supported TYPO3 version.

  2. Add Documentation/Settings.cfg, see Settings.cfg

    If this file does not exist, your documentation will get rendered, but the title will not be displayed in the left sidebar.

    Tip

    We may drop this requirement in the future, but for now it is recommended to at least add a minimal Documentation/Settings.cfg

  3. Add new webhook, see Webhook

    The legacy webhook is no longer necessary, as explained in Legacy webhook.

  4. Provide redirects

    Inform the TYPO3 Documentation Team, within #typo3-documentation Slack channel (you must register for Slack first). Alternatively, you can request a redirect by commenting in this GitHub issue The team will setup the redirects from existing legacy rendering to current rendering:

    • legacy URL: https://docs.typo3.org/typo3cms/extensions/<extkey>/<version>/
    • new URL: https://docs.typo3.org/p/<vendor>/<package>/<branch>/<locale>

Tip

Check your rendered documentation. Contact us on Slack (#typo3-documentation) if there are problems you cannot fix yourself.

Info About Changes

Extension Release

The TER (TYPO3 Extension Repository) will no longer trigger documentation rendering. Therefore uploading an extension at extensions.typo3.org does not automatically trigger rendering anymore.

In order to release a new version of an extension:

  1. Publish the extension at https://extensions.typo3.org/
  2. Add Webhook (if not already done).
  3. Tag the Git commit with a valid version.
  4. Publish the extension at https://packagist.org/ (This is done by Webhook + Tagging)

Version Numbers

There is no change necessary. https://docs.typo3.org/ does no longer show three level version numbers in form of Major.Minor.Patch. Only the first two levels are shown Major.Minor.

This reduces the amount of documentation while keeping relevant information, as patch levels should not introduce breaking changes or new features.

Supported branches

The rendering supports two branches within repositories:

master
Should contain the current development state, used for upcoming release. Every push to this branch triggers a new rendering, available at https://docs.typo3.org/p/<vendor>/<package>/master/en-us/.
documentation-draft

Should contain a draft of the documentation. Every push to this branch triggers a new rendering, available at https://docs.typo3.org/p/<vendor>/<package>/draft/en-us/ (same URL as master, except master is replaced by draft).

This state is not indexed by search engines. This branch can be used to test rendering before releasing a new version of an extension.

In order to test a different rendering, remove the branch, and create it again.

Existing Documentation

Existing legacy documentation is kept until end of 2020. Each documentation contains an information block that it’s outdated, together with a link to the necessary steps.

In order to migrate, follow Migrate Documentation. The Documentation Team can setup redirects for old documentation to new documentation afterwards. Send a message within Slack #typo3-documentation.

URL Structure

The URL structure has changed. Redirects are in place.

The URL structure now consists of the following parts:

https://docs.typo3.org/<type>/<vendor>/<package>/<version>/<locale>

Example: https://docs.typo3.org/p/helhum/typo3-console/master/en-us/

type

One of:

p
Provides documentation for composer packages (TYPO3 third party extensions)
c
Provides documentation for TYPO3 core extensions.
m
Provides official manuals (guides, tutorials, references).
h
Provides the homepage of docs.typo3.org
other
Provides further documentation, e.g. for Surf or Fluid
vendor
Collects all packages of the same vendor, e.g. “typo3” or a company providing extensions. Same as on packagist.org.
package
Defines the package. Same as on packagist.org.
version
Defines the version, either in form of “Major.Minor” or master or draft.
locale
Defines the locale, e.g. en-us or fr-fr.

Known Problems

  • Currently, the project cannot be rendered if the Start File is README.rst (or .md) and not Documentation/Index.rst. This is a known problem and already fixed in the development version of our Docker container. We will update this on the server shortly. You can use the v2.1.0 version of the Docker container locally.
  • A single-file solution (without toctree) may have problems with the menu. This is also a known problem and already fixed in development version.

Common Errors

Here we show some common errors you can and should fix yourself.

Contact us on Slack, if you need help!

Tip

We also made some changes to the example extension manual.

Make sure to use the updated version if you want to start an extension from scratch!

Missing Title

../_images/missing-title.png

Solution: Settings.cfg should contain the title (project) and release (release).

Example:

[general]

project     = Your title
release     = 2.0.0

FAQ for Extension Authors

How Do I Find My New Rendered Documentation?

Answer: Several possibilities:

  1. Search for your extension on https://docs.typo3.org/Home/Extensions.html
  2. Or, construct the URL yourself from the rules above: https://docs.typo3.org/p/<vendor>/<package>/<version>/<en-us>
  3. Or, if you just triggered rendering, look on https://intercept.typo3.com/admin/docs/deployments. The column Branch contains a link.

Is it Possible to Highjack Extension Documentation?

How do you make sure only the author of the extension publishes the documentation?

Answer: Documentation rendering is restricted to one repository per package.

I.e. if someone triggers documentation rendering with a repository with vendor myVendor and package myPackage, then nobody else will be able to trigger documentation from a different repository with that exact vendor/package name combination. You could say this works on a first come first served basis. However, if someone with malicious intent registers a package first from a fake or wrong repository, we will have to correct this by hand. The original author should in that case notify us.

Is There a Way to Manually Trigger Docs Rendering Aside From a Git Repository Push?

Answer: Yes and no. Regular users do not have this option at the moment. However, as a member of the Documentation Team you can go to https://intercept.typo3.com and log in with your typo3.org account. Then in the menu you can navigate to Documentation > Deployments. At the top right hand side you will see a button Add Configuration. By clicking this button and going through the form, you can add a repository manually without the hook. Nevertheless we strongly recommend the usage of the webhook.

Is Documentation Independant of TER?

Does the new workflow also mean that the documentation and the extension at TER (https://extensions.typo3.org) are two separate, independent entities?

Answer: Yes. In theory you could have the documentation in GitHub (for example) and the extension (code) somewhere else (or not in Git at all). You just need to fire the webhook from GitHub/GitLab/Bitbucket to trigger the documentation rendering.

Can I use a README.rst (or README.md) instead?

GitHub (or Gitlab, bitbucket) etc. automatically render a README.rst (or .md) on the repository homepage.

For TYPO3 documentation I am required to have extra documentation in a Documentation folder. This means I have to maintain 2 documentations. Or not?

Answer: No. You have these 2 options:

  1. Use a README.rst (or .md) and a Documentation/Index.rst (for example). This is done in our official manuals. The README.rst is not used as documentation, it is used as an about the repo file. The README is mostly used to direct users who come via GitHub (or Gitlab, Bitbucket etc.) to the rendered documentation on docs.typo3.org
  2. Or, use README.rst (or .md) as main documentation (Start File) and put everything in the README.rst. The Documentation/Settings.cfg file must also exist, but that is all that needs to be in the Documentation directory.

Important

About using method 2) There are currently still 2 open issues, but this is already resolved in a “development” version.

Actually, you have more options, but we do not want to make things too complicated.

Which one should you choose? That is up to you.

We recommend: Use method 1) for extensive documentation with several chapters, use method 2) for minimal documentation which can be maintained in one file.

Further Questions?

Get in touch with us, if you have problems, would like to ask questions or make suggestions.

Our team page contains information about how to contact us.

In most cases, the Slack channel #typo3-documentation is the preferred method of communication (you must register first).