This page defines the public contract for registering Cogita plugins, validating their configuration, and sharing build-time capabilities. It is the boundary used by built-in, theme, site, and community plugins.
A plugin exports a factory that receives the enhanced CogitaPluginConfig:
A factory may return one Rspress plugin, an array, or null / undefined. Disabled capabilities should return null. Core and themes should not duplicate a plugin's configuration checks.
Themes declare default capabilities through CogitaTheme.plugins. A site adds project-specific capabilities through CogitaConfig.plugins:
The final source order is core plugins → theme bridge plugins → theme plugins → site plugins. It resolves identity, source, and conflicts; it is not a serial lifecycle dependency. Rspress may invoke hooks concurrently, so plugins should coordinate through the shared contentIndex or virtual modules.
Every plugin must have a non-empty name. Strict mode stops on invalid results and factory errors while preserving the original error as cause. Non-strict mode logs a warning and skips the invalid plugin.
The theme's home layout is required. Plugins that create pages declare their layout needs:
requiredLayouts.layout matches a key in the theme's pageLayouts. when makes a requirement conditional. Core validates all requirements after plugin instantiation, before a site can publish a broken route.
Layout contracts answer whether a page exists. Capability contracts describe the data a theme or plugin needs. Identifiers use stable domain.capability strings such as content.posts.
Plugins declare providesCapabilities and requiresCapabilities. Themes use capabilities.required for hard dependencies and capabilities.optional for features that can degrade gracefully. Built-in identifiers come from COGITA_CAPABILITIES in @cogita/shared.
Core validates dependencies after all plugins are instantiated. Strict mode fails on a missing capability; strict: false emits a warning. A capability should have one provider. Multiple providers produce COGITA_CAPABILITY_PROVIDER_CONFLICT.
| Capability | Provider | Typical consumers |
|---|---|---|
content.posts |
Posts Frontmatter | Tags, collections, categories, search, post lists |
content.relations |
Content Relations | Related content, outbound links, backlinks |
content.images |
Images | Theme covers and image inventories |
content.collections |
Collections | Collection navigation |
discovery.tags |
Tags | Tag navigation |
discovery.categories |
Categories | Category navigation |
discovery.search |
Search | Search pages |
content.blog-list |
Blog List | Archives and post lists |
engagement.comments |
Comments | Article comment areas |
ui.code-copy |
Code Copy | Code block copy buttons |
ui.reading-progress |
Reading Progress | Reading progress and reading time |
syndication.rss |
RSS | RSS, Atom, and JSON Feed |
seo.metadata / seo.sitemap |
SEO / Sitemap | Search metadata and sitemaps |
addRuntimeModules passes build-time data to theme layouts. A module identifier must be unique in one build; a conflict fails in strict mode.
Core may provide safe empty modules for optional capabilities. A fallback is marked with runtimeModulePolicy: 'fallback' and can be replaced by a real provider:
Fallback modules may expose empty data or disabled state, but never absolute paths, tokens, or article bodies. Real providers keep the same module identifier and documented data shape.
The plugin instance name is its global identity and must be unique. strict defaults to true; duplicate names stop the build. With strict: false, Core keeps the first registration and warns through the shared logger.
Strict Core errors expose a stable diagnostic field. Tooling should branch on the code instead of parsing localized error text. The current schemaVersion is 1.
Important diagnostic codes include:
| Code | Scenario |
|---|---|
COGITA_THEME_LAYOUT_MISSING |
A required theme layout is missing |
COGITA_CAPABILITY_MISSING |
A dependency has no provider |
COGITA_CAPABILITY_PROVIDER_CONFLICT |
Multiple plugins provide one capability |
COGITA_PLUGIN_INVALID |
A factory returned an invalid plugin |
COGITA_PLUGIN_DUPLICATE |
A plugin name was registered twice |
COGITA_PLUGIN_FACTORY_FAILED |
A plugin factory threw |
COGITA_PAGE_ROUTE_CONFLICT |
A page route was registered twice |
COGITA_RUNTIME_MODULE_CONFLICT |
A virtual module was registered twice |
COGITA_THEME_LOAD_FAILED |
A theme could not be resolved |
COGITA_CONTENT_DIR_NOT_FOUND |
contentDir does not exist |
Use the shared helpers for build-time services:
CogitaBuildContext includes root / cwd, the shared contentIndex, absolute themeLayouts, strict, the unified logger, and framework metadata. Legacy top-level fields remain for compatibility; new build-time services belong in this context.
Use lifecycle hooks for one responsibility:
beforeBuild: read the content index, prepare files, and validate configuration.addPages: generate additional pages without rescanning articles.addRuntimeModules: expose serialized build data to browser code.afterBuild: write reports or artifacts; do not rewrite generated pages.Core attaches contractVersion to buildContext and contentIndex. Virtual modules export cogitaVirtualModuleVersion. Import COGITA_VIRTUAL_MODULE_IDS, COGITA_CAPABILITIES, and createCogitaVirtualModule from @cogita/shared instead of hard-coding public identifiers.
At minimum, test:
enabled: false returning null;