Skip to content

Offline, privacy-first grammar checker. Fast, open-source, Rust-powered

feat(web): produce graphs and tables for reports (#3858)

Elijah Potterdf6d660013d8
diff --git a/Dockerfile b/Dockerfile
index 8b2148b89..c863520c5 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -47,6 +47,7 @@ WORKDIR /usr/build/packages/harper-editor
RUN pnpm build
WORKDIR /usr/build/packages/web
+ENV ENABLE_ADMIN_ROUTES=false
RUN pnpm install --engine-strict=false --shamefully-hoist
RUN pnpm build
diff --git a/justfile b/justfile
index 66c6bbc9a..2a52b59df 100644
--- a/justfile
+++ b/justfile
@@ -162,7 +162,7 @@ build-web: build-harperjs build-lint-framework build-components build-harper-edi
cd "{{justfile_directory()}}/packages/web"
pnpm install
- pnpm build
+ ENABLE_ADMIN_ROUTES=false pnpm build
# Start a development server for Harper Desktop.
dev-desktop: build-harperjs build-lint-framework build-components build-harper-editor
@@ -444,9 +444,9 @@ check-rust: audit-dictionary
cargo hack check --each-feature
# Perform format and type checking.
-check: check-rust check-js build-web
+check: check-rust check-js
-check-js: build-harperjs build-lint-framework build-components build-harper-editor
+check-js: build-harperjs build-lint-framework build-components build-harper-editor build-web
#!/usr/bin/env bash
set -eo pipefail
@@ -455,7 +455,7 @@ check-js: build-harperjs build-lint-framework build-components build-harper-edit
# Needed because Svelte has special linters
cd "{{justfile_directory()}}/packages/web"
- pnpm check
+ ENABLE_ADMIN_ROUTES=false pnpm check
# Populate build caches and install necessary local tooling (tools callable via `pnpm run <tool>`).
setup: build-harperjs test-harperjs test-vscode build-web build-wp build-obsidian build-chrome-plugin
diff --git a/packages/components/src/lib/GutterCenter.svelte b/packages/components/src/lib/GutterCenter.svelte
index eb3eb7ea5..7c352a26d 100644
--- a/packages/components/src/lib/GutterCenter.svelte
+++ b/packages/components/src/lib/GutterCenter.svelte
@@ -1,5 +1,5 @@
<div class="flex flex-row justify-center h-full">
- <div class="lg:w-[1024px] w-full h-full">
+ <div class="w-full h-full max-w-5xl">
<slot />
</div>
</div>
diff --git a/packages/components/src/lib/Isolate.svelte b/packages/components/src/lib/Isolate.svelte
index 0b9ad980b..f66557f32 100644
--- a/packages/components/src/lib/Isolate.svelte
+++ b/packages/components/src/lib/Isolate.svelte
@@ -1,3 +1,3 @@
-<div class="fixed left-0 top-0 w-screen h-screen bg-white dark:bg-black z-1000">
+<div class="fixed left-0 top-0 w-screen h-screen bg-white dark:bg-black z-1000 overflow-auto">
<slot />
</div>
diff --git a/packages/components/src/lib/styles.css b/packages/components/src/lib/styles.css
index 0b35f5a97..84b392bc9 100644
--- a/packages/components/src/lib/styles.css
+++ b/packages/components/src/lib/styles.css
@@ -8,6 +8,8 @@
@source "./node_modules/flowbite-svelte/**/*.{svelte,ts,js}";
@theme {
+ --font-serif: Domine, serif;
+
--color-primary-50: #fef4e7; /* honey bronze */
--color-primary-100: #fce9cf;
--color-primary-200: #f9d49f;
diff --git a/packages/harper-editor/src/lib/styles.css b/packages/harper-editor/src/lib/styles.css
index ebf498bb9..abc97afd5 100644
--- a/packages/harper-editor/src/lib/styles.css
+++ b/packages/harper-editor/src/lib/styles.css
@@ -4,6 +4,10 @@
@source "./**/*.{svelte,ts}";
+@theme {
+ --font-serif: Domine, serif;
+}
+
.harper-editor {
--harper-editor-font-size: inherit;
}
diff --git a/packages/web/src/hooks.server.ts b/packages/web/src/hooks.server.ts
index 206d2da48..978590587 100644
--- a/packages/web/src/hooks.server.ts
+++ b/packages/web/src/hooks.server.ts
@@ -1,10 +1,22 @@
+import { error, type Handle } from '@sveltejs/kit';
import { migrate } from 'drizzle-orm/mysql2/migrator';
+import { ENABLE_ADMIN_ROUTES } from '$env/static/private';
import { db } from '$lib/db';
-// Migrate exactly once at startup
+// Migrate the database exactly once at startup
try {
await migrate(db, { migrationsFolder: './drizzle', migrationsTable: '__drizzle_migrations' });
} catch (e: any) {
console.log('Failed to migrate database.');
console.error(e);
}
+
+export const handle: Handle = async ({ event, resolve }) => {
+ const adminRoutesEnabled = ENABLE_ADMIN_ROUTES === 'true';
+
+ if (!adminRoutesEnabled && event.route.id?.startsWith('/admin')) {
+ error(404, 'Not found');
+ }
+
+ return resolve(event);
+};
diff --git a/packages/web/src/lib/components/AnalyticsPage.svelte b/packages/web/src/lib/components/AnalyticsPage.svelte
new file mode 100644
index 000000000..a07c5d57c
--- /dev/null
+++ b/packages/web/src/lib/components/AnalyticsPage.svelte
@@ -0,0 +1,46 @@
+<script lang="ts">
+import { GutterCenter, Isolate } from 'components';
+import BarChart from './BarChart.svelte';
+
+type Props = {
+ data: Record<string, number>;
+ title: string;
+ links: Record<string, string>;
+};
+
+let { data, title, links }: Props = $props();
+
+let counts = $derived(data);
+let entries = $derived(Object.entries(counts).toSorted(([_a, a], [_b, b]) => b - a));
+</script>
+
+<Isolate>
+ <h1>{title}</h1>
+
+ <div class="flex flex-row [&>a]:px-4">
+ {#each Object.entries(links) as [name, href]}
+ <a href={href}>{name}</a>
+ {/each}
+ </div>
+
+ <GutterCenter >
+ <BarChart data={counts} title="Most Commonly Complained-About Lint IDs"/>
+
+ <table>
+ <thead>
+ <tr>
+ <th>Lint ID</th>
+ <th>Value</th>
+ </tr>
+ </thead>
+ <tbody>
+ {#each entries as [key, value] }
+ <tr>
+ <th scope="row">{key}</th>
+ <td>{value}</td>
+ </tr>
+ {/each}
+ </tbody>
+ </table>
+ </GutterCenter>
+</Isolate>
diff --git a/packages/web/src/lib/components/BarChart.svelte b/packages/web/src/lib/components/BarChart.svelte
new file mode 100644
index 000000000..2352dcc94
--- /dev/null
+++ b/packages/web/src/lib/components/BarChart.svelte
@@ -0,0 +1,121 @@
+<script lang="ts">
+import Chart from 'chart.js/auto';
+import { onMount } from 'svelte';
+
+interface Props {
+ data?: Record<string, number>;
+ title: string;
+}
+
+let { data = {}, title }: Props = $props();
+
+let chartCanvas = $state<HTMLCanvasElement>();
+let chart: Chart | null = null;
+
+let sortedEntries = $derived(Object.entries(data).toSorted(([_a, a], [_b, b]) => b - a));
+let keys = $derived(sortedEntries.map(([a]) => a));
+let values = $derived(sortedEntries.map(([, b]) => b));
+
+onMount(() => {
+ // Create a new Chart.js bar chart on mount
+ chart = new Chart(chartCanvas!, {
+ type: 'bar',
+ data: {
+ labels: keys,
+ datasets: [
+ {
+ data: values,
+ borderColor: 'rgba(80, 80, 80, 1)',
+ borderWidth: 2,
+ borderRadius: 6, // Rounded corners
+ barPercentage: 0.6, // Thicker bars
+ },
+ ],
+ },
+ options: {
+ responsive: true,
+ maintainAspectRatio: false,
+ plugins: {
+ title: {
+ display: true,
+ text: title,
+ color: '#444', // Dark gray text
+ font: {
+ size: 18,
+ weight: 'bold',
+ },
+ },
+ legend: {
+ display: false,
+ },
+ },
+ scales: {
+ x: {
+ grid: {
+ color: '#ddd',
+ },
+ ticks: {
+ color: '#333',
+ font: {
+ size: 14,
+ },
+ },
+ },
+ y: {
+ beginAtZero: true,
+ grid: {
+ color: '#ddd',
+ },
+ ticks: {
+ stepSize: 1,
+ color: '#333',
+ font: {
+ size: 14,
+ },
+ },
+ },
+ },
+ },
+ });
+});
+
+// Update the chart data with new lint counts
+function updateChart() {
+ if (chart) {
+ chart.data.labels = keys;
+ chart.data.datasets[0].data = values;
+ chart.update();
+ }
+}
+
+// Whenever data changes, update the chart
+$effect(() => {
+ if (data) {
+ updateChart();
+ }
+});
+</script>
+
+
+<style>
+ /* Wrap the chart in a container to control layout and background */
+ .chart-container {
+ background: #f9f9f9; /* Subtle off-white background */
+ border: 1px solid #ccc; /* Light gray border */
+ border-radius: 8px; /* Rounded corners */
+ padding: 1rem;
+ width: 100%;
+ max-width: 700px; /* Adjust as needed */
+ height: 400px; /* Fixed height for the chart area */
+ margin: 0 auto; /* Center horizontally */
+ }
+
+ canvas {
+ width: 100%;
+ height: 100%;
+ }
+</style>
+
+<div class="chart-container">
+ <canvas bind:this={chartCanvas}></canvas>
+</div>
diff --git a/packages/web/src/lib/components/LintKindChart.svelte b/packages/web/src/lib/components/LintKindChart.svelte
index 008b44cf5..19779b3a0 100644
--- a/packages/web/src/lib/components/LintKindChart.svelte
+++ b/packages/web/src/lib/components/LintKindChart.svelte
@@ -1,113 +1,9 @@
<script lang="ts">
-import Chart from 'chart.js/auto';
-import { lintKindColor } from 'lint-framework';
-import { onMount } from 'svelte';
+import BarChart from './BarChart.svelte';
// Receive lint counts from the parent component
export let lintCounts: Record<string, number> = {};
-
-let chartCanvas: HTMLCanvasElement;
-let lintChart: Chart | null = null;
-
-// Update the chart data with new lint counts
-function updateChart() {
- if (lintChart) {
- lintChart.data.labels = Object.keys(lintCounts);
- lintChart.data.datasets[0].data = Object.values(lintCounts);
- lintChart.update();
- }
-}
-
-onMount(() => {
- // Create a new Chart.js bar chart on mount
- lintChart = new Chart(chartCanvas, {
- type: 'bar',
- data: {
- labels: Object.keys(lintCounts),
- datasets: [
- {
- label: 'Number of Corrections Applied',
- data: Object.values(lintCounts),
- backgroundColor: Object.keys(lintCounts).map(lintKindColor),
- borderColor: 'rgba(80, 80, 80, 1)',
- borderWidth: 2,
- borderRadius: 6, // Rounded corners
- barPercentage: 0.6, // Thicker bars
- },
- ],
- },
- options: {
- responsive: true,
- maintainAspectRatio: false,
- plugins: {
- title: {
- display: true,
- text: 'Most Common Kinds of Corrections',
- color: '#444', // Dark gray text
- font: {
- size: 18,
- weight: 'bold',
- },
- },
- legend: {
- display: false,
- },
- },
- scales: {
- x: {
- grid: {
- color: '#ddd',
- },
- ticks: {
- color: '#333',
- font: {
- size: 14,
- },
- },
- },
- y: {
- beginAtZero: true,
- grid: {
- color: '#ddd',
- },
- ticks: {
- stepSize: 1,
- color: '#333',
- font: {
- size: 14,
- },
- },
- },
- },
- },
- });
-});
-
-// Whenever lintCounts changes, update the chart
-$: if (lintChart) {
- updateChart();
-}
</script>
-<style>
- /* Wrap the chart in a container to control layout and background */
- .chart-container {
- background: #f9f9f9; /* Subtle off-white background */
- border: 1px solid #ccc; /* Light gray border */
- border-radius: 8px; /* Rounded corners */
- padding: 1rem;
- width: 100%;
- max-width: 700px; /* Adjust as needed */
- height: 400px; /* Fixed height for the chart area */
- margin: 0 auto; /* Center horizontally */
- }
-
- canvas {
- width: 100%;
- height: 100%;
- }
-</style>
+<BarChart data={lintCounts} title="Most Common Kinds of Corrections" />
-<div class="chart-container">
- <canvas bind:this={chartCanvas}></canvas>
-</div>
diff --git a/packages/web/src/lib/db/models/ProblematicLints.ts b/packages/web/src/lib/db/models/ProblematicLints.ts
index c95c08e13..b7e6a4f81 100644
--- a/packages/web/src/lib/db/models/ProblematicLints.ts
+++ b/packages/web/src/lib/db/models/ProblematicLints.ts
@@ -1,3 +1,4 @@
+import { gte } from 'drizzle-orm';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { db } from '..';
import { problematicLintTable } from '../schema';
@@ -17,4 +18,15 @@ export default class ProblematicLints {
public static async create(rec: ProblematicLintSubmission) {
await db.insert(problematicLintTable).values(rec);
}
+
+ public static async getAll(): Promise<ProblematicLintRow[]> {
+ return await db.select().from(problematicLintTable);
+ }
+
+ public static async getAllSince(date: Date) {
+ return await db
+ .select()
+ .from(problematicLintTable)
+ .where(gte(problematicLintTable.timestamp, date));
+ }
}
diff --git a/packages/web/src/lib/db/models/UninstallFeedback.ts b/packages/web/src/lib/db/models/UninstallFeedback.ts
index b0147c3ef..b7bcdbb4a 100644
--- a/packages/web/src/lib/db/models/UninstallFeedback.ts
+++ b/packages/web/src/lib/db/models/UninstallFeedback.ts
@@ -1,3 +1,4 @@
+import { gte } from 'drizzle-orm';
import { createInsertSchema, createSelectSchema } from 'drizzle-zod';
import { db } from '..';
import { uninstallFeedbackTable } from '../schema';
@@ -17,4 +18,11 @@ export default class UninstallFeedback {
public static async create(rec: UninstallFeedbackSubmission) {
await db.insert(uninstallFeedbackTable).values(rec);
}
+
+ public static async getAllSince(date: Date) {
+ return await db
+ .select()
+ .from(uninstallFeedbackTable)
+ .where(gte(uninstallFeedbackTable.timestamp, date));
+ }
}
diff --git a/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.ts b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.ts
new file mode 100644
index 000000000..39747eed3
--- /dev/null
+++ b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.server.ts
@@ -0,0 +1,42 @@
+import { redirect } from '@sveltejs/kit';
+import UninstallFeedback from '$lib/db/models/UninstallFeedback';
+
+export const load = async ({ params }) => {
+ const slug = params.slug;
+
+ let date = null;
+
+ switch (slug) {
+ case 'last30days':
+ date = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+ break;
+ case 'lastday':
+ date = new Date(Date.now() - 24 * 60 * 60 * 1000);
+ break;
+ case 'all':
+ date = new Date(0);
+ break;
+ }
+
+ if (date == null) {
+ redirect(302, '/admin/ext-uninstall-reasons/all');
+ }
+
+ const problematicLints = await UninstallFeedback.getAllSince(date);
+
+ const counts: Record<string, number> = {};
+
+ for (const item of problematicLints) {
+ const id = item.feedback ?? 'OTHER';
+
+ if (counts[id] === undefined) {
+ counts[id] = 1;
+ } else {
+ counts[id] += 1;
+ }
+ }
+
+ return {
+ counts,
+ };
+};
diff --git a/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.svelte b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.svelte
new file mode 100644
index 000000000..9575991d9
--- /dev/null
+++ b/packages/web/src/routes/admin/ext-uninstall-reasons/[slug]/+page.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+import AnalyticsPage from '$lib/components/AnalyticsPage.svelte';
+import type { PageProps } from './$types';
+
+let { data }: PageProps = $props();
+let links = {
+ All: '/admin/ext-uninstall-reasons/all',
+ 'Last 30 Days': '/admin/ext-uninstall-reasons/last30days',
+ 'Last Day': '/admin/ext-uninstall-reasons/lastday',
+};
+</script>
+
+<AnalyticsPage data={data.counts} title="Most Common Reasons to Uninstall the Chrome Ext" {links}/>
diff --git a/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.ts b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.ts
new file mode 100644
index 000000000..32f684802
--- /dev/null
+++ b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.server.ts
@@ -0,0 +1,42 @@
+import { redirect } from '@sveltejs/kit';
+import ProblematicLints from '$lib/db/models/ProblematicLints';
+
+export const load = async ({ params }) => {
+ const slug = params.slug;
+
+ let date = null;
+
+ switch (slug) {
+ case 'last30days':
+ date = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+ break;
+ case 'lastday':
+ date = new Date(Date.now() - 24 * 60 * 60 * 1000);
+ break;
+ case 'all':
+ date = new Date(0);
+ break;
+ }
+
+ if (date == null) {
+ redirect(302, '/admin/problematic-lints/all');
+ }
+
+ const problematicLints = await ProblematicLints.getAllSince(date);
+
+ const counts: Record<string, number> = {};
+
+ for (const item of problematicLints) {
+ const id = item.rule_id ?? 'OTHER';
+
+ if (counts[id] === undefined) {
+ counts[id] = 1;
+ } else {
+ counts[id] += 1;
+ }
+ }
+
+ return {
+ counts,
+ };
+};
diff --git a/packages/web/src/routes/admin/problematic-lints/[slug]/+page.svelte b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.svelte
new file mode 100644
index 000000000..6e8f103a4
--- /dev/null
+++ b/packages/web/src/routes/admin/problematic-lints/[slug]/+page.svelte
@@ -0,0 +1,13 @@
+<script lang="ts">
+import AnalyticsPage from '$lib/components/AnalyticsPage.svelte';
+import type { PageProps } from './$types';
+
+let { data }: PageProps = $props();
+let links = {
+ All: '/admin/problematic-lints/all',
+ 'Last 30 Days': '/admin/problematic-lints/last30days',
+ 'Last Day': '/admin/problematic-lints/lastday',
+};
+</script>
+
+<AnalyticsPage data={data.counts} title="Most Reported Erroring Lint IDs" {links}/>
diff --git a/packages/web/src/routes/docs/contributors/website/+page.md b/packages/web/src/routes/docs/contributors/website/+page.md
index bd0038839..0c2d6ac5d 100644
--- a/packages/web/src/routes/docs/contributors/website/+page.md
+++ b/packages/web/src/routes/docs/contributors/website/+page.md
@@ -1,154 +1,64 @@
----
-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 site
+---
+title: Website
+---
+
+This page describes how to develop [writewithharper.com](https://writewithharper.com) locally.
+Make sure you read the [introduction to contributing](./introduction) and [committing](./committing) guides before opening a pull request.
+
+## Environment
+
+Make sure you have [Set up your environment](./environment).
+
+## 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 navigation pane.
+
+## Updating the Documentation
+
+The Harper documentation (available on this site) is in `web/src/routes/docs`. It is written in Markdown.
+
+## Running the Site
+
+The recommended way to start a dev server:
+
+```bash
+just dev-web
+```
+
+This builds all the site's dependencies and runs a development server.
+You do not need to rerun anything to hot-reload changes to the `web` package.
+If you make changes to a dependency package (i.e. `components`, `harper-editor`), you MUST rerun `just dev-web` to see the changes appear on the development site.
+
+> `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.
+
+## Database
+
+The web application needs a database available for some functionality, but not most.
+You can spin up a development database locally using `docker-compose.dev.yml`.
+You can make a copy of `docker-compose.yml` to run a full instance of the entire web application.
+
+## Admin Pages
+
+Admin pages, available at `/admin` are hidden by default, but can be enabled by setting the `ENABLE_ADMIN_ROUTES=true` environment variable before building the site.
+At the time of writing, they are not admin routes as much as they are insights into the reports submitted by users.
+
+## Deployment
+
+Merges to `web-prod` trigger the **Build Web** workflow, which builds the root `Dockerfile` and publishes the site image via a private TeamCity instance.
+
+## 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 site