Configuration

The extension is configured in two places, and they do different jobs:

Where	Decides
Scheduler task	Which pages are analysed, and which pairs are stored.
TypoScript	How the stored pairs are displayed, and how the backend module renders.

A third place, the extension configuration in Admin Tools > Settings > Extension Configuration, only acts as a fallback — see Extension configuration.

Scheduler task

Create a Semantic Suggestion: Generate Similarities task in the Scheduler module. Its fields:

startPageId

Type: integer
Default: 1

Page the analysis starts from. It may be a site root or any page below it; the subtree is walked to full depth. The site the page belongs to is resolved automatically and stored separately — see Database columns.

qualityLevel

Type: float
Default: 0.3

Storage threshold, between 0.1 and 1.0. A pair scoring below it is not written to the database, so it can never be displayed either.

The threshold applied is exactly this value, floored at 0.05. No offset is applied. Lowering it later requires a full re-run to produce the missing pairs.

excludePages

Type: string
Default: (empty)

Comma-separated page UIDs that are not analysed at all, for example 42,56,78.

recursiveExclusion

Type: boolean
Default: 1

When enabled, an excluded page takes its whole subtree with it.

When disabled, only the excluded page itself is skipped and its children are still analysed. Note that those children are then collected without the exclusion list, so an excluded page nested under another excluded page is analysed in that mode.

languageId

Type: integer
Default: -1

-1 analyses every language configured on the site in a single run, which is what a multilingual site normally wants. Set an explicit language ID only when you need a different quality level per language, and create one task per language — see A multilingual site.

Note

The task also carries a legacy minimumSimilarity property. It is now a read-only mirror of the storage threshold; setting it has no effect. A task saved before qualityLevel existed is migrated on its next run, the old value becoming the quality level.

Scheduling: daily or weekly, off-peak. Each run deletes and rewrites only its own rows, identified by root_page_id + scope_page_id + sys_language_uid, so several tasks can coexist — one per site, or one per subtree of a site.

TypoScript

All settings live under plugin.tx_semanticsuggestion_suggestions.settings and are exposed to the Constant Editor under the category semantic_suggestion. The extension loads its own TypoScript instance-wide, so overrides belong in a site's root template.

Display

qualityLevel

Type: float
Default: 0.3
Path: plugin.tx_semanticsuggestion_suggestions.settings

Display filter. Stored pairs scoring below this value are not shown.

It is independent from the task's quality level. Setting it lower than the task's simply shows everything that was stored; setting it higher shows fewer, better matches. It can never reveal a pair that was never stored.

maxSuggestions

Type: integer
Default: 3
Path: plugin.tx_semanticsuggestion_suggestions.settings

Number of suggestions rendered, after exclusions and the language check.

excludePages

Type: string
Default: (empty)
Path: plugin.tx_semanticsuggestion_suggestions.settings

Page UIDs that are never shown as a suggestion. This does not stop those pages from displaying suggestions of their own, and it does not save any processing — the pairs were still computed and stored. To skip a page entirely, exclude it in the scheduler task instead.

excerptLength

Type: integer
Default: 100
Path: plugin.tx_semanticsuggestion_suggestions.settings

Maximum number of characters of the excerpt; longer text is cut and suffixed with an ellipsis.

excerptSources

Type: string
Default: bodytext,description,abstract
Path: plugin.tx_semanticsuggestion_suggestions.settings

Ordered list of sources for the excerpt; the first non-empty one wins. bodytext means the rendered content of the page. Not exposed in the Constant Editor.

debugMode

Type: boolean
Default: 0
Path: plugin.tx_semanticsuggestion_suggestions.settings

Writes verbose entries to typo3temp/logs/semantic_suggestion.log and appends a debug block to the rendered plugin output. Never enable it in production.

Analysis

analyzedFields

Type: array of float
Default: title 1.5, description 1.0, keywords 2.0, abstract 1.2, content 1.0
Path: plugin.tx_semanticsuggestion_suggestions.settings

Page fields fed to the analysis, and their weight. content falls back to the bodytext of the page's content elements when the page field is empty.

Warning

Weights are coarse. A field's text is repeated max(1, round($weight)) times before vectorisation, so:

1.0, 1.2 and 1.4 all behave identically (repeated once),
1.5 to 2.4 are repeated twice,
0 does not disable a field — it is still included once.

recencyWeight

Type: float
Default: 0.2
Path: plugin.tx_semanticsuggestion_suggestions.settings

Share of the final score taken from the recency comparison:

score = semanticSimilarity * (1 - recencyWeight) + recencyBoost * recencyWeight

Warning

recencyBoost is the absolute difference between the two pages' normalised ages (over a 30-day window), not their freshness. Raising this weight therefore favours pairs of pages that were modified at different times, and it lets a pair with no textual similarity at all reach recencyWeight as a score. Leave it low, or at 0 if you want the score to be purely textual.

enableStemming

Type: boolean
Default: 1
Path: plugin.tx_semanticsuggestion_suggestions.settings

Reduces words to their stem before vectorising. Only affects languages for which nlp_tools ships a stemmer — see Language handling.

defaultLanguage

Type: string
Default: en
Path: plugin.tx_semanticsuggestion_suggestions.settings

Last-resort language code, used only when neither the site configuration nor content analysis nor languageMapping could determine one.

languageMapping

Type: array of string
Default: (unset)
Path: plugin.tx_semanticsuggestion_suggestions.settings

Legacy mapping of language UID to language code, for example languageMapping.1 = de. Only consulted after the site configuration and content analysis have both failed, which does not happen on a site with a proper locale. Keep it unset unless you know you need it.

Important

The analysis settings above are read through the Extbase configuration manager, which needs a server request. Under a CLI run (typo3 scheduler:run, i.e. the normal cron case) there is none, so the task falls back to the extension configuration and then to the built-in defaults listed here. Do not count on TypoScript to tune the analysis in a cron-driven setup — the defaults are what will be used.

Backend module

Six booleans toggle the sections of the module, all enabled by default: showStatistics, showPerformanceMetrics, showLanguageStatistics, showTopSimilarPairs, showDistributionScores, showTopSimilarPages.

Template integration

overrideBootstrapTemplates

Type: boolean
Default: 0
Path: plugin.tx_semanticsuggestion_suggestions.settings

Registers the shipped Bootstrap Package page templates so suggestions appear automatically after the main content. Opt-in, and to be enabled in the constants of the Bootstrap Package site only — see Bootstrap Package.

Settings that are accepted but ignored

These appear in older documentation and in configurations carried over from previous versions. No code reads them, so they can be dropped:

Setting	Status
`minTextLength`	Never read. There is no minimum text length enforced by this extension; a page with no text simply produces no vector and therefore no pair. No longer present in the shipped TypoScript.
`confidenceThreshold`	Never read. The language-detection confidence check lives inside `nlp_tools` and is not configurable from here. No longer present in the shipped TypoScript.
`proximityThreshold`	Legacy name of the display threshold. It is only consulted when `qualityLevel` is absent, and the shipped setup always sets `qualityLevel` — so editing it has no effect. Use qualityLevel.
`persistence.storagePid`	The plugin stores no records.

Extension configuration

Admin Tools > Settings > Extension Configuration > semantic_suggestion offers parentPageId, proximityThreshold, maxSuggestions and excerptLength. They are a fallback only:

the backend module uses them when the corresponding TypoScript setting is missing,
the analysis uses this section when TypoScript is unreachable (the CLI case described above),
the frontend plugin never reads them,
parentPageId is read by no code at all.

Database columns

tx_semanticsuggestion_similarities holds two different page references, and mixing them up is the usual cause of "my suggestions disappeared":

Column	Meaning
`page_id`	The page the suggestions belong to.
`similar_page_id`	A page suggested for it.
`similarity_score`	Score of the pair, 0.0 to 1.0.
`root_page_id`	The site: UID of the site root page, resolved automatically. The frontend filters on it, which is what keeps suggestions inside a site.
`scope_page_id`	The task: the `startPageId` that produced the row. Several values may share one `root_page_id` when different tasks cover different subtrees of one site.
`sys_language_uid`	Language the pair was computed in.
`source`	Producer of the row: `analysis` for this extension, `solr` for `semantic_suggestion_solr`. Each deletes only its own rows.

Note

Before 4.1.0 the column root_page_id held the task's startPageId and scope_page_id did not exist. See Upgrade.