a21glossary for TYPO3

Organizations that need a glossary usually have an SEO problem

Explaining technical terms on a website sounds like a service feature. In reality, a21glossary solves a concrete technical problem: TYPO3 pages with content that requires explanation rank better when terms are internally linked, indexable as standalone pages, and instantly accessible via tooltips. The extension automatically generates links from a central term database throughout the content, without editors having to set each link manually.

For companies with specialist portals, knowledge platforms, or products that require explanation, a21glossary creates exactly the internal linking structure that Google interprets as topical authority. Instead of hiding 50 terms in an FAQ, 50 independent, indexable pages with Schema markup potential are created.

Typical use cases

Specialist portals with more than 100 terms. Industry associations, universities, and trade publishers maintain glossaries with hundreds of entries. a21glossary automatically links each term wherever it appears in body text. For one client with 340 glossary entries, internal linking density increased by 28%, measurable through Google Search Console.

Product pages with technical vocabulary. Machine manufacturers, chemical companies, and medical device makers use specialized language that buyers and decision-makers do not always understand. A tooltip with 2-3 sentences of explanation keeps readers on the page instead of sending them to Google. Time on page increases, bounce rate decreases.

Multilingual knowledge platforms. Combined with TYPO3’s language handling, glossaries can be maintained per language. German terms link to German explanations, English to English. This works cleanly as long as the language configuration in TYPO3 is set up correctly.

Technical architecture

a21glossary works as a content post-processor. After TYPO3 renders a page, the extension scans the HTML output for defined terms and replaces them with linked variants. The terms themselves are stored in a dedicated database table and managed as records in the List module.

Since version 12.0.0 the extension hooks into the page output via the PSR-14 event AfterCacheableContentIsGeneratedEvent, up to version 11 via the contentPostProc-all hook. This means it only intervenes after TYPO3 has fully rendered the content. As a result, it works independently of the content element type - whether Textmedia, News, or Custom Content Elements.

Tooltip display is handled by the browser: a21glossary writes the explanation as a title attribute into abbr, acronym or dfn tags and ships no JavaScript. Anyone who wants to style the tooltip should use a CSS-only solution to avoid impacting Core Web Vitals. Using the title attribute and a :hover selector, simple tooltips can be realized without a single line of JavaScript.

The glossary entries themselves are configurable via TypoScript: which pages should be scanned, which term types are linked, and which HTML areas are excluded (navigation, footer, other glossary entries).

Common problems and solutions

Performance degradation with large glossaries. From approximately 500 terms onward, the post-processing step can become noticeable, especially on text-heavy pages. The solution: activate caching. TYPO3’s page cache stores the result after the first rendering. Only when the cache is cleared does reprocessing occur. Additionally, reducing the term list to the actually used vocabulary helps - 200 precise terms outperform 800 including variants.

Incorrect links inside existing links. By default, a21glossary also links within existing hyperlinks; headings h1 to h6 are excluded out of the box. This leads to nested links that are HTML-invalid. The TypoScript configuration lets you add the a tag to the default list: excludeTags = acronym,abbr,dfn,h1,h2,h3,h4,h5,h6,input,pre,script,a. This setting belongs in every initial installation.

Conflicts with RealURL and routing. In older TYPO3 versions (before v9), issues arose when glossary detail pages were routed via RealURL. With TYPO3 v10+ and native Site Routing, this problem no longer exists. Anyone still using RealURL should migrate regardless.

Migration and version compatibility

a21glossary was originally developed for TYPO3 3.x and updated over the years. Sven Wappler (WapplerSystems) has maintained the extension since 2017; for TYPO3 v12 the TER lists his version 12.0.1, which ports the extension to the new TCA structure and changed hook system. For TYPO3 v13 there is version 13.0.0 via Composer (Packagist); it is not yet in the TER.

For the step from v11 to v12, WapplerSystems adapted the extension itself in version 12.0.0: first, switching from $GLOBALS['TYPO3_CONF_VARS']['SC_OPTIONS'] to the new Event Dispatcher system; second, updating the TCA definitions. The TypoScript setup stayed the same; users only update the extension.

Those planning for TYPO3 v13 face a decision: update to a21glossary 13.0.0 or switch to an alternative solution. One alternative is implementing the glossary functionality directly as a Custom Content Element with DataProcessor. The effort is approximately 2-3 developer days, the result is future-proof and independent of third-party maintenance. Gosign has performed this migration for multiple projects and can realistically estimate the actual effort based on an analysis of the existing glossary data.