This guide covers the conventions that keep a Cogita site easy to evolve: a clear repository boundary, small configuration, composable themes and plugins, reliable content, and a deployment path that can be diagnosed.
Keep site content separate from framework packages. The site repository should own configuration, content, assets, and any local extensions; Cogita packages should be installed as dependencies.
Use contentDir for handbook-style documents and posts.dir for article collections. A Knowledge site can expose both through one theme, while a Docs site normally uses contentDir as its primary source.
Choose one primary information architecture and keep URLs stable:
Do not encode temporary workflow states into public URLs. Keep drafts in a dedicated folder or use frontmatter, then publish without changing the final route.
Start with the smallest useful configuration and add capabilities only when the site needs them.
Keep responsibilities in their own namespaces:
site contains branding, language, URL, and base path.contentDir and posts describe where content comes from.theme selects the rendering system.themeConfig contains navigation and theme-specific presentation.rss, search, and comments contain their own options.Use English as the default fallback so a new installation is usable before a message dictionary is complete. Add a second dictionary only when the site is ready to offer a real language choice.
@cogita/plugin-i18n translates interface copy used by themes and plugins. It does not translate Markdown, article titles, or user metadata. Localized content should be authored as localized content and published through the site's content strategy.
Write frontmatter for both readers and machines. Use a concise title, a useful description, and stable dates.
# heading, followed by a meaningful ## structure.Avoid headings that only describe a visual element. A heading should still make sense in the table of contents and in search results.
Keep draft content out of production builds. Preview it locally with the same base path and theme that production uses, so broken links and asset paths are caught before publishing.
Treat a theme as the site's rendering boundary and a plugin as a capability provider:
Themes should declare the plugins and layouts they need. Plugins should validate their own namespace, return null when not configured, and expose build data through stable virtual modules.
| Site shape | Recommended theme | Primary strength |
|---|---|---|
| Product handbook or API reference | @cogita/theme-docs |
Navigation, sidebars, and focused reading |
| Personal blog or content archive | @cogita/theme-lucid |
Lightweight publishing and archives |
| Editorial technical site | @cogita/theme-editorial |
Reading rhythm and featured writing |
| Wiki, research notes, or mixed sources | @cogita/theme-knowledge |
Search, topics, and backlinks |
If a feature is useful to more than one theme, make it a plugin. If it changes page composition, make it a theme extension. Keep site-specific business rules in the site repository.
Use the public types from @cogita/shared for custom plugins and layouts. Avoid importing internal files from another package; internal imports make upgrades harder and can break an otherwise valid consumer.
The most valuable performance work for a static site is usually reducing unnecessary work and keeping the generated output cacheable.
For GitHub Pages, the workflow should build the docs site, validate the staged artifact, and publish the generated directory. The important checks are:
For a custom host, use / as the production base. For a project Pages site, use the repository path consistently in site.base and builderConfig.output.assetPrefix.
Use site.title, site.description, and page frontmatter as separate layers:
Use semantic headings, visible focus states, keyboard-operable controls, and labels for search and language controls. Do not use color alone to communicate state.
Check the build output for the first SSG error. A global UI component must be safe to execute in Node during static rendering and must include any runtime imports required by its compiled output.
Rebuild workspace packages, then verify the package name and the selected theme's declared dependencies.
Inspect the generated HTML and confirm that links include the configured base path. Use pnpm run check:pages-artifact before pushing a deployment change.
Confirm that the site has an i18n dictionary for the requested locale, that the fallback text in the theme is English, and that the browser language switcher is visible only when at least two locales are configured. Remember that this does not change Markdown content.
Check its configuration namespace and whether the selected theme consumes the plugin's layout or virtual module. A correctly designed optional plugin should remain silent when its capability is not configured.