YAML Indexer Configuration
In addition to creating indexer configurations as database records in the TYPO3 backend, you can define indexer configurations in YAML files within your extensions or sitepackages.
YAML-based indexer configurations allow you to keep search configuration version-controlled, automated, and deployment-friendly without requiring manual database records.
File Location and Discovery
ke_search automatically discovers YAML configuration files located in the following directory of any active TYPO3 extension:
EXT:<my_extension>/Configuration/KeSearch/IndexerConfigurations/
All files ending in .yaml or .yml within this folder (including
subdirectories) are automatically loaded in deterministic alphabetical order.
Important
YAML indexer configuration files are loaded and activated automatically as soon as the containing extension is active - without any further review or approval in the TYPO3 backend. This is different from database indexer configurations, which can only be created or changed by backend users who have the necessary access rights.
Because of this, a YAML indexer configuration file must be treated with
the same level of trust as PHP extension code: only place such files in
extensions or sitepackages that come from trusted sources (e.g. your own
development team or vetted third-party extensions). Do not allow
untrusted parties (e.g. via file uploads, unreviewed composer
dependencies, or writable directories) to place files into
Configuration/ of an active extension,
since this would let them control indexing behaviour (e.g.
storagepid, targetpid, which tables/fields are indexed) without
any further checks.
For the same reason, symbolic links pointing outside of the extension's own directory are not followed when scanning for configuration files.
YAML Schema and Structure
Each YAML file defines a single indexer configuration.
General Properties (All Indexer Types)
Required Properties
identifier(string): Unique machine-name identifier for the indexer configuration (e.g.main_,pages news_).archive title(string): Human-readable title displayed in backend modules and logs.type(string): The registered indexer type key (page,tt_,content news,tt_,address file,tt_, or custom indexer key).news
Common Optional Properties
storagepid(integer, default:0): Page UID where search index records are stored.pid(integer, default:storagepid): "Virtual" Page UID where search index configuration is stored, for compatibility with indexer configurations from the database, falls back tostoragepidif not set.hidden(boolean or integer, default:false/0): Set totrue/1to disable this indexer configuration.filteroption(integer, default:0): UID of a filter option / tag to automatically assign to all records indexed by this configuration.
Properties by Indexer Type
Page Indexer (type: page)
Indexes standard TYPO3 pages and aggregates their content elements into a single search result per page.
startingpoints_(array of integers or comma-separated string): Starting page UIDs to index recursively.recursive single_(array of integers or comma-separated string): Specific single page UIDs to index non-recursively.pages index_(array of integers or comma-separated string, default:page_ doctypes 1): Page types (doktype) to index (1= standard page).index_(boolean or string:content_ with_ restrictions yes/no, default:no): Index content elements even if frontend user group access restrictions are set.contenttypes(array of strings or comma-separated string, default: `text,textmedia,textpic,bullets,table,html,header,uploads,shortcut, accordion,tab,carousel,carousel_`) to index.fullscreen,carousel_ small,icon_ group, card_ group,timeline``): Content element types (``CType content_(array of strings or comma-separated string, default:fields bodytext,subheader,header_): Fields from thelink tt_table to include in fulltext indexing.content page_(array of strings or comma-separated string, default: empty, since version 7.5.0): Text fields from thefields pagestable to append to the indexed content for each page language.page_(array of strings or comma-separated string, default: empty, since version 7.5.0): Text fields from thefields_ hidden pagestable to add as searchable hidden content, which is not shown in search result content. Only fields of the TCA typesinput,textandemailare indexed. Code fields (likeTSconfig) and fields which are only visible to admins are skipped. Do not index sensitive values. These settings do not create index entries for pages without indexable content.additional_(YAML mapping, array, or INI string): Configuration for indexing content from child/related database tables (e.g. EXT:bootstrap_package accordion/tab/carousel items, EXT:mask, EXT:content_blocks).tables fileext(array of strings or comma-separated string, default:pdf,ppt,doc,xls,docx,xlsx,pptx): Allowed file extensions for linked files to index.file_(array of strings or comma-separated string, default:reference_ fields media): Database fields intt_holding file references whose linked files should be indexed.content index_(boolean or integer, default:use_ page_ tags_ for_ files 0): If set totrue/1, tags assigned to the parent page will be applied to indexed linked files.
For example, add the page author to the indexed content and page keywords as hidden searchable content:
page_fields:
- author
page_fields_hidden:
- keywords
Content Element Indexer (type: tt_content )
Indexes individual content elements separately. Each matching content element generates its own search result linking directly to the element via an anchor link.
startingpoints_(array of integers or comma-separated string): Starting page UIDs to index recursively.recursive single_(array of integers or comma-separated string): Specific single page UIDs to index non-recursively.pages contenttypes(array of strings or comma-separated string, default: `text,textmedia,textpic,bullets,table,html,header,uploads,shortcut, accordion,tab,carousel,carousel_`) to index.fullscreen,carousel_ small,icon_ group, card_ group,timeline``): Content element types (``CType content_(array of strings or comma-separated string, default:fields bodytext,subheader,header_): Fields from thelink tt_table to include in fulltext indexing.content additional_(YAML mapping, array, or INI string): Configuration for indexing content from child/related database tables.tables fileext(array of strings or comma-separated string, default:pdf,ppt,doc,xls,docx,xlsx,pptx): Allowed file extensions for linked files to index.file_(array of strings or comma-separated string, default:reference_ fields media): Database fields intt_holding file references whose linked files should be indexed.content index_(boolean or integer, default:use_ page_ tags_ for_ files 0): If set totrue/1, tags assigned to the parent page will be applied to indexed linked files.
News Indexer (type: news - EXT:news)
Indexes news records from EXT:news (tx_).
sysfolder(array of integers or comma-separated string): Storage folder UIDs containing news records.startingpoints_(array of integers or comma-separated string): Starting page/folder UIDs for recursive folder lookup.recursive targetpid(integer, default:0): Target page UID where the news detail view plugin is located.-
index_(integer, default:news_ category_ mode 1, or2if categories are specified):1: Index all news records regardless of assigned categories.2: Index only news records matching the selected categories (index_).extnews_ category_ selection
index_/extnews_ category_ selection category_(array of category UIDs or category titles, or comma-separated string): System categories to filter by whenselection index_isnews_ category_ mode 2. The generic aliascategory_can be used instead, e.g. for custom indexers.selection -
index_(integer, default:news_ archived 0):0: Index all news records (active and archived).1: Index active (non-archived) news only.2: Index archived news only.
-
index_(integer, default:news_ files_ mode 0):0: Index attached file content into the news search result.1: Index attached files as separate search results.
fileext(array of strings or comma-separated string, default:pdf,ppt,doc,xls,docx,xlsx,pptx): Allowed file extensions for attached files.index_(boolean or integer, default:use_ page_ tags 0): If set totrue/1, tags assigned to the parent storage folder will be added to the indexed news records.
Address Indexer (type: tt_address - EXT:tt_address)
Indexes address records from EXT:tt_address (tt_).
sysfolder(array of integers or comma-separated string): Storage folder UIDs containing address records.startingpoints_(array of integers or comma-separated string): Starting page/folder UIDs for recursive folder lookup.recursive targetpid(integer, default:0): Target page UID for single view / address display.index_(boolean or integer, default:use_ page_ tags 0): If set totrue/1, tags assigned to the parent storage folder will be added to indexed address records.
File Indexer (type: file)
Indexes files directly from directories on the file system or FAL (File Abstraction Layer) storage.
directories(array of strings or newline/comma-separated string): Directory paths to index recursively (e.g.fileadmin/or relative path within the FAL storage likedocuments/ documents/). Enter.to index all files in the storage.fal_(integer, default:storage 0): UID of the FAL storage record (sys_), orfile_ storage 0to index directly from the file system without FAL.file_(array of integers or comma-separated string): UIDs ofcollections sys_records to index.file_ collection fileext(array of strings or comma-separated string, default:pdf,ppt,doc,xls,docx,xlsx,pptx): Allowed file extensions to index.
News Indexer (type: tt_news - EXT:tt_news)
Indexes news records from legacy EXT:tt_news (tt_).
sysfolder(array of integers or comma-separated string): Storage folder UIDs containing news records.startingpoints_(array of integers or comma-separated string): Starting page/folder UIDs for recursive folder lookup.recursive targetpid(integer, default:0): Target page UID where the single view plugin is located.-
index_(integer, default:news_ files_ mode 0):0: Index attached file content into the news search result.1: Index attached files as separate search results.
fileext(array of strings or comma-separated string, default:pdf,ppt,doc,xls,docx,xlsx,pptx): Allowed file extensions for attached files.index_(boolean or integer, default:use_ page_ tags 0): If set totrue/1, tags assigned to the parent storage folder will be added to indexed news records.
Custom Indexers (type: <custom_key> )
For custom indexers registered via hooks or event listeners:
- All common properties (such as
identifier,title,type,storagepid,targetpid,startingpoints_,recursive sysfolder,filteroption,hidden) are supported. category_(array of category UIDs or category titles, or comma-separated string): Generic alias forselection index_, useful for custom indexers that need to filter by categories.extnews_ category_ selection - Any custom scalar properties defined in YAML are automatically passed
through and accessible in
$this->indexerwithin your custom indexer class.Config
Examples
Page Indexer Example
identifier: site_pages
title: 'Main Website Pages'
type: page
storagepid: 10
startingpoints_recursive:
- 1
fileext:
- pdf
- docx
News Indexer Example
identifier: news_articles
title: 'Company News & Blog'
type: news
storagepid: 10
sysfolder:
- 25
targetpid: 30
index_news_category_mode: 2
index_extnews_category_selection:
- 5
- 12
Custom indexer example
You can also register your custom indexers in YAML configurations. Just set
the type field ot the type you chose in your custom indexer. You can also
pass custom options to custom indexer.
identifier: my_custom_indexer
title: 'My Custom indexer'
type: tx_news_domain_model_news
storagepid: 3
targetpid: 8
sysfolder: 6
my_custom_indexer_option: 123
Page Indexer with Custom Content Fields Example
When indexing custom content elements (e.g. built with EXT:mask or
EXT:content_blocks), you can add custom database fields to the index using
content_ and file_:
identifier: site_pages_custom_fields
title: 'Pages with Custom Content Fields'
type: page
storagepid: 10
startingpoints_recursive:
- 1
content_fields:
- bodytext
- subheader
- header_link
- tx_myextension_customfield
- tx_myextension_teaser
file_reference_fields:
- media
- tx_myextension_custom_files
contenttypes:
- text
- textmedia
- my_custom_ctype
Content Blocks Example
Content elements created with EXT:content_blocks store their custom fields
directly on the tt_ table (add them to content_ /
file_ as needed), while repeating/child elements are
stored in additional tables which reference the tt_ record via
the field foreign_. Use additional_ to index
those child tables. Internally the ini format is used, but here you need
to use the YAML format (it's converted internally):
identifier: site_pages_content_blocks
title: 'Pages with Content Blocks Elements'
type: page
storagepid: 10
startingpoints_recursive:
- 1
contenttypes:
- text
- textmedia
- myvendor_mycontentblock
content_fields:
- bodytext
- subheader
- header_link
- myvendor_mycontentblock_teaser
additional_tables:
myvendor_mycontentblock:
table: myvendor_mycontentblock_collection
referenceFieldName: foreign_table_parent_uid
fields:
- header
- bodytext
In this example the additional_ key myvendor_ must
match the CType of the Content Blocks element (also listed in
contenttypes). If a Content Blocks element has multiple additional
tables (e.g. for repeating child elements), you can add further
configurations for the same CType by appending a dot and an index to
the key, e.g. myvendor_, myvendor_.
Synthetic UIDs and Category Handling
Because YAML configurations do not exist in the database table
tx_, ke_search assigns them stable, deterministic
negative UIDs derived from their identifier.
These synthetic negative UIDs:
- Never clash with auto-increment database record UIDs.
- Ensure consistent tracking and status reporting across indexing runs.
- Support category filtering transparently through in-memory category resolution.
Title-Based Category Selection
When defining category restrictions (e.g. for the News indexer), you can specify categories using their titles in addition to numeric database UIDs.
How It Works
Category settings such as index_ accept:
- Category titles (e.g.
"News","Press Releases"). - Numeric database record UIDs (e.g.
5,12). - Formatted as YAML lists or comma-separated strings (e.g.
"News, Events").
When the indexer configuration is loaded and normalized, ke_search queries the
sys_ table and resolves the category titles (matching
case-insensitively against the title field) to their
corresponding record UIDs. If a category title cannot be found in the
database, ke_search logs a warning message and skips the unresolvable entry
while continuing to process any valid categories.
Example
The following example shows a News indexer configuration filtering news records by category titles:
identifier: news_press_releases
title: 'Press Releases News Indexer'
type: news
storagepid: 10
sysfolder:
- 25
targetpid: 30
index_news_category_mode: 2
index_extnews_category_selection:
- 'News'
- 'Press Releases'