Configuratorlink

Simai\Docara\Configurator is the core helper that collects, structures, and exposes localized docs metadata for Docara builds (menus, breadcrumbs, prev/next, headings, translations). It is resolved from the container and wired into the build lifecycle; you don’t instantiate it manually.

Core purposelink

• Read per-locale docs trees (e.g., source/_docs-<lang>/).
• Load .lang.php translations and .settings.php metadata.
• Build hierarchical menus and flattened navigation structures.
• Store headings and generate unique anchors.
• Provide helpers for breadcrumbs and prev/next navigation.

How it’s wired (Docara core)link

• Registered as a singleton (configurator) in ConfiguratorServiceProvider.
• Injected during lifecycle events in DocaraEventsServiceProvider:
  • beforeBuild: merges locales (from cache + project), prepares the configurator, stores it in config (configurator), attaches locale/sha metadata.
  • afterCollections: parses page headings, sets paths, builds search indexes (INDEXES).
  • afterBuild: injects heading anchors into HTML, writes search-index_<lang>.json.

Because it is bound in core, templates can access it via $page->configurator (or app('configurator')) without manual setup.

Usage in templates/configlink

• Prev/Next navigation: $page->configurator->getPrevAndNext($page->getPath(), $page->language)
• Breadcrumbs: $page->configurator->generateBreadCrumbs($page->language, $segments)
• Translations: $page->configurator->getTranslate($key, $page->language)

Index resolution and menu fallbackslink

• If indexPage is not set in config.php, the configurator picks a landing page automatically (locale root index.md, else the first real page).
• For category trees, when a category item has no own index.md, the menu now points to the first descendant that does have an index (applies recursively, so nested folders without an index still resolve to the first child with an index).

File/folder conventions (per locale)link

Key responsibilitieslink

• Translations: makeLocales() loads .lang.php per locale into $translations.
• Settings: makeSettings() scans .settings.php, builds the tree, flattens menus ($flattenMenu, $realFlatten), and constructs nested $menu.
• Headings: setHeading() stores parsed headings; makeUniqueHeadingId() creates stable IDs for anchors.
• Paths: setPaths() collects page paths; used for search index generation.

Lifecycle touchpoints (core)link

• beforeBuild: configurator prepared and exposed via config; locales merged from cached .config.json + project config.php.
• afterCollections: headings extracted, paths stored, INDEXES populated for search.
• afterBuild: anchors injected, search indexes written to disk.

Search index outputlink

Per-locale search data is written to the build destination as search-index_<lang>.json, containing title, url, language, plain content, and headings for each page.

Noteslink

• Configurator expects locale folders named after your DOCS_DIR prefix, e.g., docs_en, docs_ru (or DOCS_DIR_en if you customize the prefix).
• Cached locales come from temp/translations/.config.json (or your cache_dir); they are merged automatically by core events.
• You no longer need to touch bootstrap.php to wire the configurator; Docara core handles registration and lifecycle calls.