A theme is an independent npm package. In addition to visual styling, it can declare the plugins and page layouts it needs. A site selects the theme in its configuration and installs the theme package directly.
Then select it in cogita.config.ts:
Themes receive site-level options through themeConfig. Keep navigation, sidebars, and theme-specific options there instead of putting theme implementation details into Core configuration.
| Theme package | Best for | Visual position |
|---|---|---|
@cogita/theme-docs |
Cogita handbooks | Documentation navigation, sidebars, and API reading |
@cogita/theme-lucid |
Independent blogs and content sites | Lightweight hero, post cards, and content sidebar |
@cogita/theme-editorial |
Content-first technical publishing | Editorial typography, featured posts, and focused reading |
@cogita/theme-knowledge |
Personal wikis, research notes, and mixed knowledge bases | Unified content, search, topics, and backlinks |
A theme is the site's rendering boundary: Core handles configuration, routes, and builds; plugins provide data; the theme decides how to organize that data. When adding a theme, add a theme package and theme-specific configuration before changing Core.
Lucid reads site branding from site.title and site.description, and accepts its own options through themeConfig.lucid:
heroEyebrow, heroCopy, postsTitle, showSidebar, and featuredPost are optional. Lucid uses stable English-first defaults when they are omitted; topics, categories, collections, and search remain provided by their respective plugins.
Knowledge puts posts and contentDir behind one content entry point and combines search, topics, and content relations by default. It is designed for knowledge bases that need long-term accumulation, cross-references, and revisiting:
When a site maintains both posts and ordinary documents, Knowledge presents both content types on the home page, in search, and in content relations. Content quality diagnostics remain opt-in through contentCheck. See the complete information architecture in the Knowledge theme guide.
If the page structure needs to change, create your own theme package, reuse the shared types and UI components, and declare the required plugins inside that theme. The site only needs to switch the theme package; its content and framework packages do not need to migrate.
See the theme development guide and architecture design for layout contracts, plugin dependencies, and theme resolution.