Cogita is a theme-driven static site framework. Its architecture keeps site content, rendering decisions, reusable capabilities, and generated output on separate boundaries while allowing them to compose through typed contracts.
Cogita starts with sensible defaults:
The default path should produce a useful site. Advanced configuration should extend that path rather than replace it with framework internals.
A theme is more than a visual skin. It defines page layouts, styles, navigation conventions, and the default plugin capabilities needed to make its reading experience coherent.
The same project can grow through three levels:
Core, themes, and plugins communicate through public types, the shared ContentIndex, capability identifiers, and versioned virtual modules. A consumer should not need to import private files from another package.
The site repository owns content, branding, configuration, and local extensions. Core resolves the configuration and assembles the build. Themes own the reading surface. Plugins own reusable data or behavior. The generated directory is the handoff boundary to a host such as GitHub Pages.
The configuration lifecycle is:
Configuration responsibilities remain separated:
| Boundary | Responsibility |
|---|---|
| Site config | Branding, paths, content sources, and enabled capabilities |
| Core | Resolution, normalization, registration, validation, and assembly |
| Theme | Layouts, styles, navigation, and reading experience |
| Plugin | Data collection, generated pages, runtime modules, and diagnostics |
| Rspress | Markdown processing, rendering, bundling, and output |
Themes are runtime dependencies of the consumer site. Core resolves the configured package from the site project, loads its theme entry point, and validates the returned CogitaTheme. A legacy shorthand may remain for compatibility, but new sites should install and name their theme package explicitly.
A theme entry point declares the rendering boundary:
Core resolves layout paths relative to the theme package that returned them. This keeps a theme portable and prevents the consumer from depending on a repository-specific directory.
Themes provide default plugin factories. Sites can add project-specific factories through the plugins option. The registry records each plugin's name and source, flattens factory results, validates the plugin shape, and detects conflicts.
This order resolves identity and conflicts; it is not a serial lifecycle dependency. Hooks may run concurrently, so plugins must not use array order to coordinate scanning or data preparation.
The registry validates:
Strict mode stops the build for invalid or ambiguous contracts. Non-strict mode preserves the first registration where possible and emits a stable diagnostic through the shared logger.
A plugin that creates a theme page declares the layout key it needs. Core validates this after all plugins are instantiated, so a missing page layout fails before deployment.
Capabilities use stable domain.capability identifiers. A plugin can provide or require a capability, while a theme can classify it as required or optional. Built-in identifiers should come from COGITA_CAPABILITIES in @cogita/shared.
An optional capability must have a safe visual fallback. A required capability should fail early when no provider exists. Multiple providers for one capability are ambiguous and fail in strict mode.
Content plugins collect and normalize source data into the shared ContentIndex. Themes and other plugins can consume the same index without rescanning the file system.
The index is the stable handoff between collection and presentation. A plugin should read the index through CogitaBuildContext and should only read full document bodies when its feature needs them.
Some build-time data must reach browser-side theme components. Plugins expose that data through virtual modules:
Every public module identifier must be unique during one build and should carry its contract version. Use the shared module helpers and identifiers instead of inventing a second spelling for an existing contract.
Fallback modules may expose empty arrays or a disabled state for optional features. They must never expose machine paths, credentials, private configuration, or unneeded source content.
The build is organized around explicit phases:
Plugins should assign one responsibility to each hook:
Development mode loads the same configuration and theme contracts as production, then starts the Rspress server with file watching. Production mode renders the static output and runs the configured artifact checks.
Keeping these paths aligned matters for adoption: a site author should be able to reproduce a deployment failure locally using the same base path, content sources, theme, and plugins.
For a project hosted under a repository path, keep site.base and builderConfig.output.assetPrefix aligned:
Use a plugin when a capability can serve more than one theme or site. Use a theme extension when the feature changes page composition or visual hierarchy. Keep product-specific rules and content in the consumer repository.
This division lets Core remain stable while the ecosystem grows:
Build context, content index, and virtual modules carry explicit version information where the contract is shared. Additive fields are preferred. When a breaking change is unavoidable, update the public types, design document, consumer examples, and Changeset together.
The architecture is successful when a theme can evolve its presentation, a plugin can evolve its capability, and a site can upgrade packages without copying framework internals or rewriting its content model.