Florian Thiele
This initiative, which began on 1 October 2024, is on track to be completed by 31 December 2024, with the goal of enabling extension authors to use Markdown for documentation in TYPO3. This update brings the flexibility to switch seamlessly between Markdown and reStructuredText (RST) as needed. We’re taking a moment to highlight what’s already been accomplished and what this means for the TYPO3 Community moving forward.
The Problem
TYPO3 documentation currently relies on reStructuredText (RST), which, though powerful, has a learning curve that can discourage contributions. Many developers are more comfortable with Markdown, a simpler and widely used format in the PHP community. Since writing documentation isn’t usually a developer’s favorite task, being able to work in familiar Markdown should make it a lot easier. This initiative aims to fully support CommonMark Markdown in TYPO3, letting developers use the format they already know and prefer.
What is CommonMark?
CommonMark is a standardized version of Markdown, designed to create consistency across Markdown implementations. Unlike traditional Markdown, which can vary in features across tools, CommonMark follows strict guidelines to ensure predictable, universal rendering. By adopting CommonMark, TYPO3 aims to bring Markdown documentation into its ecosystem without sacrificing consistency or rendering quality.
Key Achievements So Far
Our work to implement full support for CommonMark in the TYPO3 render-guides project has reached several important milestones, each addressing core needs of extension developers who prefer Markdown.
- Enhanced Markdown Parser in phpdocumentor/guides
We started by improving the upstream Markdown parser in the phpdocumentor/guides project, ensuring that it now supports the complete CommonMark feature set. This improvement forms the backbone of our Markdown implementation, making it possible for TYPO3 documentation to align with widely used standards and offer a familiar experience for Markdown users.
- Refined Inline Structure for Rich Text Options
To provide authors with the flexibility they need, we changed the internal structure of inline nodes to allow strong and italic text, including combinations like italic bold. This enhancement ensures that rich formatting options are available in Markdown, bringing it closer to the typographic flexibility users enjoy in RST.
- Example Documentation in Markdown
To showcase our progress and help users familiarize themselves with the new functionality, we’ve created a sample Markdown document. This example demonstrates Markdown’s capabilities in TYPO3 and highlights features that users can explore and implement in their own projects.
- Automatic Menu Generation
While Markdown doesn’t natively support menu creation, we’ve addressed this by adding a feature that automatically generates a menu based on file structure and document headings. This enhancement makes it easier for authors to organize and navigate their Markdown-based documentation, bringing a level of structure traditionally associated with RST to Markdown.
- Inline Link Detection
We have integrated support for inline link detection, allowing links to be recognized and rendered without additional configuration. This improvement saves authors time and provides a seamless, user-friendly linking experience within their Markdown documentation.
- Support for GitHub-Style Admonitions
GitHub-style admonitions are now supported, offering a way to highlight important information like notes, warnings, and tips. This addition aligns Markdown documentation with industry standards and lets authors create visually distinct blocks to emphasize crucial points.
- Front Matter Tags for Metadata
We’ve also added support for front matter tags, enabling authors to include metadata such as the document’s author, creation date, and other details. This feature is essential for keeping documentation organized and accessible, enhancing both author and reader experience.
- Preliminary Markdown-to-RST Conversion Tool
For authors who start their documentation journey in Markdown but wish to transition to RST, we’ve developed a first working version of a Markdown-to-RST conversion tool. This tool is a key part of our long-term vision to allow TYPO3 users to choose the format that best meets their needs, without the worry of being locked into one format.
- Draft Rendering of Powermail Documentation
As part of testing our current setup, we rendered the Powermail documentation, which yielded promising results. Powermail documentation is now live with the new Markdown support. This example demonstrates how our Markdown implementation handles complex documentation structures, providing a real-world view of its capabilities.
- Extended Features Through render-guides
With Markdown rendering integrated into the render-guides project, it benefits from the same core features available in the TYPO3 template for RST. This includes interaction on headers, consistent rendering of code blocks, and integration with other tools, such as the watch functionality created by Garvin Hicking.
- Interlinking Between RST and Markdown Documentation
Another standout feature we’re proud of is interlinking between RST and Markdown documentation. It gives authors a new level of flexibility, linking Markdown and RST content directly, which makes navigating complex documentation easier.
What’s Next?
As we move toward our project’s end goal, our focus remains on refining and finalizing each of these features to ensure a smooth, high-quality experience for TYPO3 users. By the end of December 2024, we aim to achieve full CommonMark support and provide TYPO3 extension developers with the flexibility to choose the documentation format that best suits their workflows.
The Impact
This initiative not only makes TYPO3 more accessible for developers accustomed to Markdown, but it also expands the documentation options within TYPO3 itself. Extension authors can start with Markdown for simplicity and later switch to RST if they require advanced formatting features. The added flexibility also lowers barriers for new contributors, allowing them to work in a familiar syntax, which aligns directly with TYPO3’s commitment to inclusivity, flexibility, and user-centric development.
