From f067c12762d6936043459a68d5c284d5793032bd Mon Sep 17 00:00:00 2001 From: kim-benedict <213380729+kim-benedict@users.noreply.github.com> Date: Sat, 3 Oct 2026 18:10:36 +0900 Subject: [PATCH] fix(workspace): disambiguate docs package and document local setup --- AGENTS.md | 4 +- CONTRIBUTING.md | 102 ++++++++++++++++++++++++++++++++++++++ docs/package.json | 3 +- packages/comark/README.md | 4 ++ test/bundle.test.ts | 2 +- 5 files changed, 111 insertions(+), 4 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/AGENTS.md b/AGENTS.md index 595ef91e..ddefd8d9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,7 +36,6 @@ This is a **monorepo** containing the Comark Markdown parser, document model, pl │ ├── 3.plugins/ # Plugin examples (math, mermaid, highlight, rangi, footnotes, ...) │ └── 4.ai/ # AI streaming examples (Nuxt + AI SDK) ├── docs/ # Documentation site (comark-docs layer) -├── playground/ # Nuxt playground (`pnpm dev:playground`) ├── benchmarks/ # mitata benchmarks for parse/render/plugins ├── scripts/ # Build/sync/release scripts ├── test/ # Root-level tests (bundle-size snapshot) @@ -824,6 +823,8 @@ export const DocsMarkdown = defineMarkdownComponent({ ## Common Tasks +See [CONTRIBUTING.md](./CONTRIBUTING.md) for local setup and the example-app workflow. Installation runs `pnpm stub`, so examples normally use package sources without a separate compiler watcher. Run `pnpm stub` again after a build to restore those source exports. + ### Adding a new utility function 1. Internal helpers go in `packages/comark/src/internal/`; public ones in `packages/comark/src/utils/` @@ -870,7 +871,6 @@ Root workspace scripts: ```bash pnpm docs # Run documentation site pnpm dev: # Run an example (vue, react, svelte, angular, html, ansi, nuxt, nextjs, astro, ...) -pnpm dev:playground # Run the Nuxt playground pnpm build # Build all packages, then sync plugin re-exports pnpm stub # Point every package's dist/ at src/ for local dev (runs on postinstall) pnpm test # Run all package tests diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..ed9150e3 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,102 @@ +# Contributing to Comark + +Thanks for contributing! For a bug fix, include a reproduction and a regression test. If you are planning a new API or a larger change, an issue is a good place to discuss the scope before implementation. + +## Local setup + +Use Node.js 24 (the version used in CI) and the pnpm version pinned in the root `package.json`. With Corepack installed, enable it before installing dependencies: + +```sh +corepack enable +pnpm install +``` + +Run commands from the repository root unless a different directory is shown. Installation runs `pnpm stub`: package `dist/` files re-export their TypeScript sources, and `pnpm sync-plugins` adds plugin re-exports to the renderer packages. These files are generated and should not be committed. + +## Develop with an example + +The default example is the Vue app in `examples/2.vite/vue`: + +```sh +pnpm dev +``` + +Other examples have their own root scripts, including `pnpm dev:react`, `pnpm dev:svelte`, `pnpm dev:angular`, `pnpm dev:html`, and `pnpm dev:nuxt`. Use the example for the renderer you are changing. + +With source stubs in place, example bundlers load local package sources directly. You do not normally need a second terminal running `pnpm dev:packages`. + +`pnpm build` replaces the stubs with compiled output. After building, restore source exports before continuing development: + +```sh +pnpm stub +``` + +If you want to develop against compiled output instead, run `pnpm dev:packages` in a separate terminal alongside the example. This runs the available package compiler watchers; packages without a `dev` script still need their own build command. For Svelte's compiler watcher, use `pnpm --dir packages/comark-svelte run build:watch`. + +The documentation site uses a separate app: + +```sh +pnpm docs +``` + +## Find the right package + +- `packages/comark`: parser, document model, core plugins and Markdown string rendering. +- `packages/comark-html` and `packages/comark-ansi`: HTML and terminal renderers. +- `packages/comark-vue`, `packages/comark-react`, `packages/comark-svelte`, and `packages/comark-angular`: framework renderers. +- `packages/comark-nuxt`: Nuxt integration. +- `docs/content`: user-facing documentation. + +Keep parser-only behavior in the core package and framework-specific behavior in its renderer. The [architecture reference](./AGENTS.md) has a more detailed package map. + +## Add or change a plugin + +Core plugins live in `packages/comark/src/plugins` and use `defineComarkPlugin` from `comark/parse`. Add tests in `packages/comark/test/plugins` and document the plugin in `docs/content/4.plugins`. + +For plugins without a framework component, `pnpm sync-plugins` generates the renderer re-exports. If a plugin needs a component, add the wrapper in the relevant renderer package and keep the renderer APIs consistent. + +See the [plugin API](https://comark.dev/plugins/custom/plugin-api) for hooks and examples. + +## Check your changes + +Run the repository checks before opening a pull request: + +```sh +pnpm verify +``` + +This runs linting, package tests and the root TypeScript check. Formatting uses oxfmt, with no semicolons, single quotes and a 120-column limit. To format a file, use `pnpm exec oxfmt path/to/file`; review the diff before committing. + +For a focused parser test: + +```sh +cd packages/comark +pnpm exec vitest run test/parse/sub-sup.test.ts +``` + +Parser fixtures live in `packages/comark/SPEC` and run through `test/index.test.ts`. Parser changes should also preserve streaming behavior in `test/streaming.test.ts`. + +Svelte's local tests include a headless Chromium project. Install the browser if needed: + +```sh +pnpm exec playwright install chromium +``` + +For changes to build output or package exports, also run the build and bundle snapshot check used in CI: + +```sh +pnpm prepack +pnpm exec vitest run bundle +``` + +If your change legitimately alters package sizes, update the snapshot with `pnpm exec vitest run bundle -u` after building, and review the resulting diff. Restore source stubs with `pnpm stub` before returning to example development. + +## Prepare a pull request + +Link the relevant issue and follow the pull request template's **What** and **Why** sections. Describe the user-visible problem, the chosen fix and any compatibility impact. Include the checks you ran and any remaining limitations. + +Use Conventional Commits, for example `fix(parse): preserve inline comments`, `feat(html): add an option`, or `docs: clarify local setup`. Mark breaking changes explicitly. Maintainers use these messages to generate package releases; contributors do not need to bump versions or publish packages. + +All commits in a pull request that is ready for review must have a signature that GitHub verifies. Use a signing key registered with your GitHub account and check the commit's **Verified** status before submitting. See GitHub's [commit signing guide](https://docs.github.com/en/authentication/managing-commit-signature-verification/signing-commits). + +Report security vulnerabilities privately using [SECURITY.md](./SECURITY.md). diff --git a/docs/package.json b/docs/package.json index 7d1f97f1..efe26806 100644 --- a/docs/package.json +++ b/docs/package.json @@ -1,5 +1,6 @@ { - "name": "comark", + "name": "comark-docs-site", + "private": true, "description": "Parse and render Markdown anywhere with one JavaScript library for HTML, ANSI, Vue, React, Svelte and Angular, plus plugins and streaming.", "type": "module", "scripts": { diff --git a/packages/comark/README.md b/packages/comark/README.md index d88cc4a6..1e772103 100644 --- a/packages/comark/README.md +++ b/packages/comark/README.md @@ -160,6 +160,10 @@ npx skills add https://comark.dev See [Installation](https://comark.dev/getting-started/installation) on comark.dev for details. +## Contributing + +See the [contribution guide](https://github.com/comarkdown/comark/blob/main/CONTRIBUTING.md) for local setup, developing packages and plugins, and preparing a pull request. + ## License Made with ❤️ diff --git a/test/bundle.test.ts b/test/bundle.test.ts index 4ce4d51e..63567996 100644 --- a/test/bundle.test.ts +++ b/test/bundle.test.ts @@ -67,7 +67,7 @@ describe('package bundle size', { timeout: 60_000 }, () => { "@comark/react": "37.9k (76 files)", "@comark/svelte": "45.8k (84 files)", "@comark/vue": "56.1k (80 files)", - "comark": "375k (160 files)", + "comark": "376k (160 files)", } `) })