Florian Thiele
This decision follows months of successful implementation and positive feedback from the community about the new rendering engine.
Why the Shift?
The switch to PHP-based rendering has brought numerous improvements to the TYPO3 documentation experience, including:
- Faster rendering: One of the most significant benefits of the PHP-based system is its speed. What previously took several minutes to render in Sphinx now completes in under a minute.
- Streamlined linking: With automatic link generation for each headline, navigating and referencing sections has never been easier.
- Simplified migration: We’ve made the process of moving from the Sphinx system straightforward with our Docker-based migration tools, allowing contributors to switch without hassle.
Given the clear benefits and the overwhelmingly positive feedback, it makes sense to standardize on the PHP-based rendering engine for all documentation going forward.
What’s the Plan?
We’re planning to migrate all extension manuals to the new system. However, only newly rendered versions of manuals (i.e., new releases or changes to the master/main branch) will be affected by this transition to the PHP-based system. Documentation versions that were already rendered with Sphinx will remain accessible as they are and will not be re-rendered unless updated.
For extension authors, this means that the documentation for their extensions will soon be rendered exclusively using the PHP-based engine. As part of this process:
- The old Sphinx-based system will be completely phased out.
- We recommend that extension maintainers migrate their documentation themselves and test the new PHP-based rendering locally. This ensures the smoothest transition and allows maintainers to address any potential issues early.
- A CI pipeline will automatically switch your extension’s documentation to the new renderer. Our team will be available to support and help with any issues or questions that might arise during the transition.
Timeline for the Transition
We are aiming to complete the full transition to the PHP-based rendering system by the end of 2024. A key milestone in this process will be the TYPO3 Community Sprint in Q4/2024, which takes place 18–22 November 2024. During this event, our team will be available to address any final questions. This will also be an ideal opportunity to ensure that all extension manuals are successfully transitioned, and to provide hands-on support if needed.
The phase-out of the Sphinx-based system will happen gradually leading up to this event.
Action Required for Extension Developers
To make this transition as smooth as possible, we highly recommend that all extension authors:
- Migrate their manuals to the new system and update their documentation projects to use the new PHP-based rendering system as soon as possible.
- Test the new rendering locally to ensure everything works as expected.
Follow the Render Migration Tutorial to migrate your documentation projects to the new PHP-based rendering system.
For any questions or concerns, please don’t hesitate to reach out to the TYPO3 Documentation Team. We’re here to help make this transition as smooth as possible.