Development
Set up the repository locally and run the checks before you open a pull request.
Requirements
Setup
Clone the repository, install the dependencies, and run the full validation suite:
pnpm install
pnpm readypnpm ready runs the type checks and linter, the tests, and the production build.
Repository layout
| Path | What it is |
|---|---|
packages/core | The editor, BaseKit, feature extensions, and commands. |
packages/react | The React bindings. |
packages/extension-collaboration | The Yjs collaboration extension. |
apps/playground | The Astro playground with demos and examples. |
apps/docs | This documentation site. |
Scripts
| Command | What it does |
|---|---|
pnpm dev | Runs the playground locally. |
pnpm dev:docs | Runs this documentation site locally. |
pnpm build | Builds the published packages. |
pnpm ready | Type checks, tests, and builds. Run this before a PR. |
pnpm release:add | Creates a bump file for a release. |
pnpm release:check | Validates the release metadata. |
pnpm release:status | Shows the pending releases. |
Package-specific scripts work through pnpm filters, for example
pnpm --filter @inksane/core test.
Documentation
The docs are Markdown and MDX under apps/docs/content/docs. Run pnpm dev:docs and edit the
files; the dev server reloads them.
Navigation lives in the meta.json file next to the pages:
{
"title": "Introduction",
"collapsible": false,
"pages": ["index", "installation", "quick-start"]
}titleis the label of the folder in the sidebar.pagessets the order. Pages that are not listed are appended at the end.collapsible: falserenders the folder as a category label instead of a collapsible group, which is how the top-level sections are built."---Label---"insidepagesinserts a separator label without a folder.
Add the page file, then list it in the meta.json of its folder to control where it appears.
Deployment
.github/workflows/pages.yml builds both apps and deploys a single GitHub Pages site: the
playground at the root and the docs under /docs. A Pages deployment replaces the whole site, so
both apps have to build in the same workflow.
The docs build reads DOCS_BASE_PATH for that subpath. Without it the build targets the site root,
which is what pnpm dev:docs and a local pnpm --filter @inksane/docs build use.
DOCS_BASE_PATH=/inksane/docs pnpm --filter @inksane/docs buildLinks written in Markdown are not rewritten by Astro when a base path is set, so
plugins/rehype-base-links.mjs prefixes root-relative links and image sources with it.
Checks in CI
Every pull request runs:
pnpm --filter @inksane/docs run sync
pnpm exec vp check
pnpm exec vp run -r testvp check formats, lints, and type checks the repository. astro sync runs first because it
generates the Astro content types for apps/docs. Without them the docs app is checked against
Astro’s any fallback instead of its real collections, which hides type errors and reports a
redundant-type warning. Run it once after cloning if you work on the docs:
pnpm --filter @inksane/docs run syncRun pnpm exec vp check --fix to apply the formatting.