This guide is for contributors to the Cogita framework, themes, and plugins. It covers local development, quality checks, testing, and release validation.
Use the CLI to create a minimal blog, docs, or knowledge site:
The blog template reads posts/, the docs template reads Markdown pages from content/, and the Knowledge template reads both content types. Run pnpm run dev after generation.
Requirements:
>= 18>= 9^5Install dependencies with:
Cogita uses pnpm workspaces. Internal dependencies use workspace:*. Do not replace pnpm with npm or yarn, because that can create an incompatible lockfile.
After changing package source, run pnpm run build:packages before the docs site or tests. This prevents a site from consuming stale dist output.
preview:lucid reads the sibling cogita-blog repository by default. Set COGITA_BLOG_DIR=/path/to/cogita-blog to use another content repository. The command copies content and public assets to a temporary preview site, builds with the current workspace packages, and starts a root-path server. Production site.base should still match the deployed URL.
The demos/ directory contains four independent Cogita consumer projects, not a mirror of an existing blog. Each project has its own package.json, cogita.config.ts, and custom Markdown content:
| Demo | Theme | Content focus |
|---|---|---|
demos/docs |
@cogita/theme-docs |
Northstar engineering handbook |
demos/lucid |
@cogita/theme-lucid |
Field Notes practice journal |
demos/editorial |
@cogita/theme-editorial |
Small Systems Review |
demos/knowledge |
@cogita/theme-knowledge |
Atlas of Practice knowledge base |
Run pnpm run demo to build all four demos and serve the index at http://localhost:3100/. To develop one demo, run pnpm --filter @cogita/demo-knowledge dev and replace the package name as needed. Every new built-in theme should add a corresponding demo and index entry so contributors can verify its consumer configuration without relying on real blog content.
Personal blogs, product documentation, and other real content sites stay outside this repository and consume Cogita through published packages. This keeps framework code, handbook content, and site content on independent release boundaries.
Recommended structure:
Use the factory pattern:
A plugin should:
null when disabled or when a required capability is unavailable;getCogitaBuildContext for the shared index, layouts, and logger;cogita.requiredLayouts;cogita.providesCapabilities and cogita.requiresCapabilities;A theme combines page layouts, styles, and default plugin capabilities:
The entry point should declare layouts and plugins:
Do not validate plugin options inside a theme or hard-code a site's content into a layout. Let plugins declare page requirements and let the theme implement the corresponding pageLayouts keys.
The project uses Biome rather than ESLint or Prettier:
Keep code comments, JSDoc, TODOs, and FIXMEs in Chinese. Use strict TypeScript and avoid any outside a deliberate boundary. Use Conventional Commits, for example:
Plugin tests use Node's built-in test runner:
Core and plugin tests should cover stable defaults, safe disabling, readable configuration errors, virtual-module contracts, and missing layout behavior.
Full validation:
Before a release, also run pnpm run check:release. It checks package boundaries, minimal consumers, the independent blog consumer, and the independent docs consumer after one package build. The external blog check may skip locally when no sibling cogita-blog repository exists; the release workflow checks it explicitly.
When code changes, update the package README and the matching page under docs-site/content. Add a Changeset when a published package changes. Examples should use current package names such as @cogita/theme-lucid, not the retired 'lucid' shorthand or an old workspace command.
Do not edit package versions by hand. Record release intent with Changesets:
main.pnpm run build:packages has passed.pnpm run check and relevant tests have passed.