If you've had the chance to read our previous articles (if not, check the links below this one), you may already know that at Macopedia, we often participate in the TYPO3 Community Budget Ideas program. This program allows developers to propose changes and improvements to TYPO3, which are then voted on by the community members. The selected ideas are developed during the given quarter of the year. We successfully delivered improvements in 2024 and once again in 2025. One of our initiatives for the third quarter of 2025 focused on improving documentation indexing and search functionality.
High-quality documentation: a key component of software
Providing high-quality documentation is one of the most critical factors determining how software is perceived, adopted, and used by developers, integrators, and editors. Sometimes, even if the documentation is extensive and rich in content, finding specific information within it can be challenging. This is often due to the inefficiency of search tools that fail to filter or return results effectively.
Through our frequent use of TYPO3 documentation, we noticed areas that could be improved, particularly in how content is indexed and how search results are generated and displayed. We proposed our ideas for potential enhancements to the TYPO3 documentation in the third quarter of this year as part of the Community Budget Ideas program. These ideas were well-received by the community and approved for implementation following a vote.
Step-by-step work plan
When submitting our proposal for improvements to the TYPO3 documentation search, we prepared a detailed plan outlining the tasks to be completed. A significant portion of this plan involved analysis and consultations to define specific changes to be made from a development perspective. The key steps included:
- Consultations with the TYPO3 documentation team to determine how the search engine should function and what features it should offer.
- Engaging an ElasticSearch expert to discuss the optimal data index structure.
- Collaborating with the expert to design a data index structure that supports fast and precise searches, ensuring users receive highly relevant results.
- Modifications to the indexing application and development of API endpoints to interact with the new data index, enabling advanced search suggestions and precise results.
Brainstorming and search engine mockups
Our work began with a meeting attended by Marcin Sągol and TYPO3 documentation team leader Lina Wolf. During the discussion, Lina shared her vision for search functionality improvements and the direction the search interface should take. Her goal was to provide advanced filtering options and narrowing capabilities, comparable to search tools on platforms like GitHub or Slack.
To ensure both our development team and the TYPO3 documentation team fully understood the direction we aimed to pursue, mockups of the search engine were prepared during the first meeting (using Figma). These mockups illustrated the tool’s behavior in various user scenarios.
The new search system is designed to offer an advanced suggestion mechanism, including links to documentation pages and the ability to narrow the search scope to a specific manual (e.g., documentation for a particular extension), vendor, option, or version.
| Search scope | Description |
| global | Allows to search in all manuals (vendor/package), options and versions - any restrictions/scopes are ignored |
| manual | Allows to search only documentation which belongs to the given manual (vendor/package). Examples: georgringer/news, typo3/cms-core (so the scope is given composer package) |
| vendor | Allows to search only documentation files which belong to the given vendor. If there are multiple manuals which belong to the same vendor, they all will be searched. Example: georgringer, typo3 |
| option | This will be a new feature. Some files will contain documentation for the so-called Option. An Option will be a special group which documents related configuration like for TCA. The documentation files in the tags containing sections can contain data-search-facet attribute, which points to a section.; |
| version | This will narrow the search scope only to the given manual version |
Optimizing the ElasticSearchindex structure
To ensure the new TYPO3 documentation search engine is both fast and effective in delivering accurate, filtered results, we sought advice from an ElasticSearch expert.
We consulted Rafał Kuć, a renowned specialist and author of several ElasticSearch books. We presented our objectives to Rafał and sought his guidance on designing an optimal data index structure. The goal was to organize the data to enable filtering by documentation type, extension, version, and other criteria while maintaining high performance. A few days later, we received a set of recommendations from Rafał, which allowed us to proceed to the final implementation stage.
Development work: ElasticSearch index updates and API adjustments
TYPO3 documentation relies on manuals provided by TYPO3 team members or extension authors, generated as HTML files from reStructuredText (RST). These files undergo an indexing process managed by a Symfony-based application. During indexing, each HTML file is split into sections, enabling more precise search results by linking users directly to specific documentation fragments rather than entire pages.
The changes made to the indexing application and ElasticSearch index structure, primarily developed by Oskar Dydo, enabled the creation of an advanced search suggestion mechanism and improved search scope management. The new API allows for dynamic narrowing of search results as the user types, though multi-phrase queries are not yet supported.
All the changes were implemented in the t3docs-search-indexer repository. Additionally, we created documentation detailing the updated ElasticSearch index structure and the new API endpoints. This document provides information on query parameters, the data structure returned by the API, and a detailed explanation of the suggestion mechanism.
Summary of the TYPO3 documentation search Initiative
The primary focus of this initiative was on backend improvements. The work included extending the ElasticSearch index structure, modifying the data indexing process, and adding new API endpoints to support scenarios like narrowing search scopes or providing suggestions based on package names, vendors, versions, or options.
We hope that a new search frontend will soon be developed to fully utilize these functionalities, ultimately enhancing the user experience for those navigating TYPO3 documentation. :)
Related links:
https://macopedia.com/blog/news/typo3-documentation-search-improvements
https://macopedia.com/blog/news/access-control-lists-in-typo3-research-and-planning-improvements