Cogita produces a directory that any static file server can host. This repository uses docs-site as its handbook example; an independent blog or documentation site only needs its own content directory and configuration.
From the Cogita repository:
The output is written to docs-site/doc_build. An independent site runs pnpm exec cogita build, which normally writes to its own doc_build directory.
The repository provides .github/workflows/deploy.yml. It:
docs-site;docs-site/doc_build/demos/;docs-site/doc_build to GitHub Pages.Set Pages / Build and deployment / Source to GitHub Actions, then push to main.
The site.base value must match the deployment path. The wu9o/cogita repository uses:
For a custom domain, base is usually /; update url at the same time.
After deployment, the handbook is available at /cogita/, the demo index at /cogita/demos/, and each theme demo below its own directory. Demo builds use the same /cogita/ prefix as Pages; local pnpm run demo uses /demos/.
An independent site can reuse the same workflow with its own build and publish directory:
Do not copy the framework repository's docs-site path into an independent site. The publish directory should always be the actual build output.
If content lives in another Git repository, add a second actions/checkout before the site build and check it out to the directory configured by createGitContentSource. The repository includes examples/github-actions/external-content-deploy.yml as a starting point.
Public content repositories can use the default github.token. For private repositories, keep COGITA_CONTENT_REPOSITORY, optional COGITA_CONTENT_REF, and COGITA_CONTENT_TOKEN in repository variables and Secrets. Never place credentials in site configuration or plain workflow text.
For a Vercel project rooted at the repository root:
pnpm install --frozen-lockfilepnpm run build:docsdocs-site/doc_buildIf the Vercel root directory is already docs-site, use pnpm exec cogita build and doc_build instead. Choose one layout; do not combine root-directory and repository-root paths.
Recommended settings from the repository root:
pnpm run build:docsdocs-site/doc_buildTo publish manually:
When the project root is the repository root:
pnpm run build:docsdocs-site/doc_build/When docs-site is the root directory, use pnpm exec cogita build and doc_build.
Preview the output with any static server:
Python works as well:
Open http://localhost:8000 and check pages, assets, and internal links.
This Dockerfile works from the framework repository root:
Build and start it with:
At minimum, run:
Then verify that:
index.html;site.base matches the deployment path;Check that site.base, site.url, and builderConfig.output.assetPrefix use the same base path. Rebuild after changing them; refreshing an old doc_build directory is not enough.
The host path and base usually disagree. Repository Pages uses /repository-name/; a custom domain uses /. Do not mix the two configurations.
Themes and plugins are installed by the consumer site. Confirm the dependency exists in package.json, then run:
Local development can use /, while production must use the public path. Build once with production configuration and run pnpm --filter docs-site preview before publishing.