Offline, privacy-first grammar checker. Fast, open-source, Rust-powered
docs: add comprehensive website contribution guide (#3561)
jdgajjar8f616a4938d4
diff --git a/AGENTS.md b/AGENTS.mdindex 7e7a4beaa..146e96543 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -71,6 +71,7 @@ Agents should remind humans of this when possible.- `packages/web/src/routes/docs/contributors/author-a-rule/+page.md`: Step-by-step workflow for implementing and testing new grammar rules.- `packages/web/src/routes/docs/contributors/visual-studio-code/+page.md`: How to run, debug, test, and package the VS Code extension locally.- `packages/web/src/routes/docs/contributors/chrome-extension/+page.md`: Internal architecture and local development notes for the browser extensions.+- `packages/web/src/routes/docs/contributors/website/+page.md`: Local development, preview, and validation for writewithharper.com (SvelteKit/SveltePress).- `packages/web/src/routes/docs/contributors/wordpress/+page.md`: How to build and run the WordPress plugin locally.- `packages/web/src/routes/docs/contributors/obsidian/+page.md`: Obsidian-plugin contributor workflow and plugin-specific constraints.- `packages/web/src/routes/docs/contributors/review/+page.md`: PR reviewer playbook, including ways to fetch artifacts and test patches locally.diff --git a/packages/web/src/routes/docs/contributors/environment/+page.md b/packages/web/src/routes/docs/contributors/environment/+page.mdindex fbd75aa02..58752d857 100644--- a/packages/web/src/routes/docs/contributors/environment/+page.md+++ b/packages/web/src/routes/docs/contributors/environment/+page.md@@ -6,7 +6,7 @@ Depending on what you're wanting to work on within the Harper repo, you may notFor example, if you only intend to work on the core grammar engine, `harper-ls`, or `harper-cli`, you only need `cargo` installed.In that case, Harper follows all of the standard conventions for Rust projects, so any existing Rust knowledge will apply.-If you intend to work on the Chrome extension, Obsidian plugin, or certain other projects, you'll need the full environment set up.+If you intend to work on the Chrome extension, Obsidian plugin, the [website](./website), or certain other projects, you'll need the full environment set up.To use _all_ the tooling we use to build and debug Harper, you'll need the following programs available in your `$PATH`.Please read the manuals for each tool for instructions on how to install it.diff --git a/packages/web/src/routes/docs/contributors/website/+page.md b/packages/web/src/routes/docs/contributors/website/+page.mdnew file mode 100644index 000000000..bd0038839--- /dev/null+++ b/packages/web/src/routes/docs/contributors/website/+page.md@@ -0,0 +1,154 @@+---+title: Website+---++This page describes how to develop [writewithharper.com](https://writewithharper.com) locally.+If you are comfortable with JavaScript or TypeScript but new to Svelte, start with [Prerequisites](#Prerequisites) and [Running the Site](#Running-the-Site), then skim [Where Code Lives](#Where-Code-Lives).++Make sure you read the [introduction to contributing](./introduction) and [committing](./committing) guides before opening a pull request.++## Notes++- Almost all website code lives under [`packages/web`](https://github.com/Automattic/harper/tree/master/packages/web).+- The site is a [SvelteKit](https://kit.svelte.dev/) app. Documentation pages use [SveltePress](https://sveltepress.site/) (Markdown routes under `src/routes/docs/`).+- The homepage demo and `/editor` route use workspace packages [`harper.js`](../../harperjs/introduction), [`lint-framework`](https://github.com/Automattic/harper/tree/master/packages/lint-framework), [`harper-editor`](https://github.com/Automattic/harper/tree/master/packages/harper-editor), and [`components`](https://github.com/Automattic/harper/tree/master/packages/components). `just dev-web` builds them for you.+- You can look at the project's [`justfile`](https://github.com/Automattic/harper/blob/master/justfile) to see exactly what the `just` recipes below do.+- CI builds the production site with the [`Build Web`](https://github.com/Automattic/harper/blob/master/.github/workflows/build_web.yml) workflow (Docker image from the root [`Dockerfile`](https://github.com/Automattic/harper/blob/master/Dockerfile)).++## Prerequisites++- [Set up your environment](./environment). For website-only work you need `node`, `pnpm`, and `just` in your `$PATH`. You do **not** need a full Rust toolchain unless you are changing `harper-wasm` or `harper-core`.+- From the repository root, run `just setup` once (or at least `just build-web`) so workspace dependencies and WASM artifacts are built.+- Node **22+** and **pnpm 10** match what Harper uses in CI (see the root `package.json` `engines` field).++## Where Code Lives++| Path | Purpose |+| --- | --- |+| `packages/web/src/routes/` | Site routes: marketing pages (`.svelte`), docs (`.md`), and API handlers (`+server.ts`) |+| `packages/web/src/routes/docs/` | Contributor and user documentation (this page is `contributors/website/+page.md`) |+| `packages/web/src/lib/` | Shared Svelte components, marketing sections, and small utilities |+| `packages/web/vite.config.ts` | Vite config, SveltePress theme, and **documentation sidebar** |+| `packages/lint-framework/` | Browser linting UI (underlines, popups) reused by the site and extensions |+| `packages/harper-editor/` | Embeddable Harper editor used on the homepage and `/editor` |+| `packages/components/` | Shared UI primitives consumed by the site and other packages |+| `packages/harper.js/` | JavaScript API over `harper-wasm` |++Documentation sidebar entries are defined in `packages/web/vite.config.ts`. When you add a new doc page, register it there so it appears in the left nav.++## Running the Site++The recommended way to start a dev server:++```bash+just dev-web+```++This builds `harper.js`, `lint-framework`, `components`, and `harper-editor`, then runs `pnpm dev` in `packages/web`.++Open [http://localhost:3000](http://localhost:3000). Vite hot-reloads most edits to `.svelte`, `.ts`, and `.md` files automatically.++> `just build-web` only produces a production build; it does **not** start a dev server. Use `just dev-web` when you want to preview changes interactively.++### If You Change Lower-Level Packages++- Edits under `packages/web` usually reload without restarting.+- If you change `packages/components`, `packages/harper-editor`, or `packages/lint-framework`, rebuild that package (or re-run `just dev-web`).+- If you change `harper-wasm` / `harper-core`, re-run `just dev-web` (or `just build-harperjs`) so the site picks up a new WASM build.++### Manual Alternative++From the repo root:++```bash+just build-harperjs build-lint-framework build-components build-harper-editor+cd packages/web+pnpm install+pnpm dev+```++## Previewing Your Changes++| What you changed | Where to look |+| --- | --- |+| A documentation page | `http://localhost:3000/docs/...` (path mirrors `src/routes/docs/...`) |+| Homepage or marketing UI | `http://localhost:3000/` |+| Live grammar demo / editor | `http://localhost:3000/` (demo) or `http://localhost:3000/editor` |+| Rule catalog | `http://localhost:3000/docs/rules` |+| Weir studio | `http://localhost:3000/weir/studio` |++SveltePress doc pages support standard Markdown plus SveltePress features (admonitions, embedded code, etc.). Use an existing page under `src/routes/docs/` as a template.++Each doc page has an **Edit this page** link (configured in `vite.config.ts`) that opens the matching file on GitHub.++## Svelte and SvelteKit (For JS/TS Developers)++You do not need deep Svelte expertise for many contributions.++- **Routes**: Files in `src/routes/` map to URLs. `+page.svelte` is a page component; `+page.md` is a SveltePress doc page; `+server.ts` is a server endpoint.+- **Components**: Reusable UI lives in `src/lib/`. Import with `$lib/...` (SvelteKit alias).+- **Scripts**: `<script lang="ts">` holds component logic. Harper uses **Svelte 5** (runes like `$state` appear in newer components).+- **Styles**: Tailwind CSS v4 is enabled via `@tailwindcss/vite` in `vite.config.ts`. Component-scoped `<style>` blocks are also used.++Official references: [Svelte tutorial](https://svelte.dev/tutorial), [SvelteKit docs](https://kit.svelte.dev/docs).++## Testing and Validation++Before opening a pull request:++```bash+just format+just precommit+```++For website-focused checks:++```bash+cd packages/web+pnpm check+```++`pnpm check` runs `svelte-check` (TypeScript and Svelte diagnostics). The root `just check` recipe also runs `pnpm check` for the whole workspace and includes `just build-web`.++There is no dedicated website unit-test package today; rely on `pnpm check`, a manual click-through in the browser, and CI.++### Production Build Smoke Test++```bash+just build-web+cd packages/web+pnpm preview+```++Then open the URL printed by `vite preview` (defaults differ from dev; confirm in the terminal output).++### Docker (Optional)++Reviewers sometimes test grammar changes via the site demo using Docker ([see also the review guide](./review#Testing-Via-the-Docker-Image)):++```bash+docker build . -q+docker run -p 3000:3000 -it <image-id>+```++You do not need Docker for everyday website UI or documentation work.++## Server Features (Usually Optional)++A few routes persist data with **MariaDB** via Drizzle ORM (for example uninstall feedback and problematic-lint reports). Local API work is optional:++1. Start a database: `docker compose -f docker-compose.dev.yml up` from the repo root.+2. Set `DATABASE_URL` for `packages/web` (see `packages/web/drizzle.config.ts`).+3. Run migrations on app start (`src/hooks.server.ts`).++Most contributors never need this to change docs, marketing pages, or the public demo.++## Deployment++Merges to `master` trigger the **Build Web** workflow, which builds the root `Dockerfile` and publishes the site image. You do not need to deploy manually to test a pull request; maintainers handle production releases.++## Related Reading++- [Harper's architecture](./architecture) — how `harper-core`, `harper.js`, and integrations fit together+- [Reviewing pull requests](./review) — testing patches, including the Docker demo workflow+- [`harper.js` documentation](../harperjs/introduction) — if you are wiring lint behavior on the sitediff --git a/packages/web/vite.config.ts b/packages/web/vite.config.tsindex 92219fee9..f5d971956 100644--- a/packages/web/vite.config.ts+++ b/packages/web/vite.config.ts@@ -195,6 +195,10 @@ export default defineConfig(async () => {title: 'Chrome Extension',to: '/docs/contributors/chrome-extension',},+ {+ title: 'Website',+ to: '/docs/contributors/website',+ },{title: 'WordPress',to: '/docs/contributors/wordpress',