[FEAT] Redirect generator based on git changes.

[jaapio]

This is a prove of concept PR, showcasing how we could possibly generate a list of redirects. This is not complete and should be evaluated carefully.

The purpose of the new command is to be able to automatically create directs for file that have been removed. For now we only use the git history, but we might want to expand this. For example to use the perma links used within most documentation.

To test this command you have to build the docker file for your local development. Using make docker-build .
After that the command can be tested on you local machine.

docker run -i --rm --user 1000 -v${PWD}:/project typo3-docs:local create-redirects-from-git -b 3eb3cfc

Where 3eb3cfc is a short sha of the project you are processing. In my example I used: https://github.com/TYPO3-Documentation/TYPO3CMS-Guide-HowToDocument

The output of the command is now written to a file: redirects.nginx.conf

# Nginx redirects for moved files in Documentation
# Generated on: 2025-06-10 20:22:48

location = /HowToAddTranslation { return 301 /Advanced/HowToAddTranslation; }
location = /GeneralConventions/ReviewInformation { return 301 /Advanced/ReviewInformation; }
location = /About { return 301 /Basics/About; }
location = /BasicPrinciples { return 301 /Basics/BasicPrinciples; }
location = /GeneralConventions/CodingGuidelines { return 301 /Basics/GeneralConventions/CodingGuidelines; }
location = /GeneralConventions/ContentStyleGuide { return 301 /Basics/GeneralConventions/ContentStyleGuide; }
location = /GeneralConventions/Format { return 301 /Basics/GeneralConventions/Format; }
location = /GeneralConventions/Glossary { return 301 /Basics/GeneralConventions/Glossary; }
location = /GeneralConventions/GuidelinesForImages { return 301 /Basics/GeneralConventions/GuidelinesForImages; }
location = /GeneralConventions { return 301 /Basics/GeneralConventions; }
location = /GeneralConventions/Licenses { return 301 /Basics/GeneralConventions/Licenses; }

This is just a real quick showcase, we could implement this for example in the github action, to automatically create a pr or issue to publish the content.

[linawolf]

Thanks a lot, this patch is magic! I just tried it out and it detected the redirects just fine. I think we would need an additional parameter to tell the command which versions have to be created. we frequently have redirects like

location ~ ^/m/typo3/reference-coreapi/(main|13.4|12.4)/en-us/ExtensionArchitecture/Extbase/Reference/Domain/Model.html {
    return 303 /m/typo3/reference-coreapi/$1/en-us/ExtensionArchitecture/Extbase/Reference/Domain/Model/Index.html;
}

The other question would be how we can get the first part of the domain. We could, theoretically get it from the composer name (typo3/tutorial-getting-started) and composer type mapping.

[linawolf]

I added a commit with which you can make the version regex and path configurable. Usage:

docker run -i --rm --user 1000 -v${PWD}:/project typo3-docs:local create-redirects-from-git -b 192fc31 -r "(main|13.4)" -p '/m/typo3/reference-coreapi/'

[linawolf]

@jaapio, what would be needed to proceed here?

[jaapio]

I think we need to validate the output, and see how we can integrate this in your workflow.
So my first suggestion would be that you try it local to see if this works.

[linawolf]

Yes, I tried it locally and improved the links so that they work

[jaapio]

Let's first finish this PR by making the pipeline pass and add some tests to validated the code works as expected.

If this works and helps to generate the redirects, let's see how we can integrate this. I do see the option to run the command every time we render a documentation project. And send the output as a commit to the correct repository.
Maybe we can come to an agreement in the nginx config change to include all files in: https://github.com/TYPO3GmbH/site-intercept/tree/develop/config/nginx/

So we can maintain a file per documentation project. That would allow us to render every redirect we find in the git history from now on. As nginx loads the config on reload there is nearly any impact on the number of files it needs to include. And splitting the files makes it easier to review what happens. Rather than to maintain one large file.

[linawolf]

@jaapio the pipeline is passing, however I am not sure how to write tests for this

[linawolf]

Cool, let us test this manually!