docs: Add a javy book

.github/dependabot.yml

@@ -28,6 +28,17 @@ updates:
           - "minor"
           - "patch"
 
+  - package-ecosystem: npm
+    directory: "/book"
+    schedule:
+      interval: "monthly"
+    open-pull-requests-limit: 100
+    groups:
+      nonbreaking:
+        update-types:
+          - "minor"
+          - "patch"
+
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/workflows/book.yml

@@ -0,0 +1,76 @@
+name: Book
+
+on:
+  push:
+    paths:
+      - "docs/**"
+      - "book/**"
+      - ".github/workflows/book.yml"
+  pull_request:
+    paths:
+      - "docs/**"
+      - "book/**"
+      - ".github/workflows/book.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# Let an in-progress deployment finish rather than cancelling it halfway.
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build book
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          # Full history so each page can show when it was last updated.
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v6
+        with:
+          package_json_file: book/package.json
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: pnpm
+          cache-dependency-path: book/pnpm-lock.yaml
+
+      - run: pnpm install --frozen-lockfile
+        working-directory: book
+
+      - run: pnpm run build
+        working-directory: book
+        env:
+          # Deploy to the Pages site of whichever account owns the repo, so
+          # forks get a working preview at https://<owner>.github.io/javy/.
+          BOOK_SITE: https://${{ github.repository_owner }}.github.io
+          ASTRO_TELEMETRY_DISABLED: 1
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: book/dist
+
+  deploy:
+    name: Deploy book
+    # Upstream deploys from main only. Forks deploy from any branch, so the
+    # book can be previewed on the fork's Pages site before opening a PR.
+    if: >-
+      github.event_name != 'pull_request' &&
+      (github.ref == 'refs/heads/main' || github.repository != 'bytecodealliance/javy')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

book/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.astro/

book/astro.config.mjs

@@ -0,0 +1,70 @@
+// @ts-check
+import { readFileSync } from 'node:fs';
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import { remarkDocsLinks, remarkMermaid, remarkStripLeadingHeading } from './src/remark.ts';
+import { tableOfContents, unlistedSlugs } from './src/toc.ts';
+
+// Served from GitHub Pages at https://<owner>.github.io/javy/. CI sets
+// `BOOK_SITE` so a fork deploys to its own owner's Pages.
+const site = process.env.BOOK_SITE ?? 'https://bytecodealliance.github.io';
+const base = '/javy';
+const repo = 'https://github.com/bytecodealliance/javy';
+
+// Follows the table of contents in `docs/index.md`; pages it doesn't list
+// come last in their section. Pages are labeled with their own title, except
+// a section's landing page, whose title would repeat the section's.
+const toc = tableOfContents();
+const unlisted = unlistedSlugs(toc);
+const sidebar = toc.map(({ title, entries }) => {
+	const section = entries[0].slug.split('/')[0];
+	return {
+		label: title,
+		items: [
+			...entries.map(({ title, slug }) => (slug.includes('/') ? slug : { label: title, slug })),
+			...unlisted.filter((slug) => slug.startsWith(`${section}/`)),
+		],
+	};
+});
+
+export default defineConfig({
+	site,
+	base,
+	markdown: {
+		remarkPlugins: [remarkStripLeadingHeading, [remarkDocsLinks, { base, repo }], remarkMermaid],
+	},
+	integrations: [
+		starlight({
+			title: 'Javy',
+			description: 'Seamless JavaScript on WebAssembly: how Javy works, and how to use and extend it.',
+			social: [
+				{ icon: 'github', label: 'GitHub', href: repo },
+				{
+					icon: 'zulip',
+					label: 'Zulip',
+					href: 'https://bytecodealliance.zulipchat.com/#narrow/stream/370816-javy',
+				},
+			],
+			editLink: { baseUrl: `${repo}/edit/main/book/` },
+			// The docs embed WebAssembly text; Shiki calls the grammar `wasm`.
+			expressiveCode: { shiki: { langAlias: { wat: 'wasm' } } },
+			customCss: [
+				'@fontsource-variable/ibm-plex-sans',
+				'@fontsource/ibm-plex-mono/400.css',
+				'@fontsource/ibm-plex-mono/600.css',
+				'./src/styles/custom.css',
+			],
+			lastUpdated: true,
+			// Loaded as a plain script, not a `Head` override, so it can't clash
+			// with themes or plugins that override components.
+			head: [
+				{
+					tag: 'script',
+					attrs: { type: 'module' },
+					content: readFileSync(new URL('./src/mermaid.js', import.meta.url), 'utf8'),
+				},
+			],
+			sidebar,
+		}),
+	],
+});

book/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "javy-book",
+  "type": "module",
+  "private": true,
+  "packageManager": "pnpm@10.28.0",
+  "scripts": {
+    "dev": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview"
+  },
+  "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.3",
+    "@astrojs/starlight": "^0.42.6",
+    "@fontsource-variable/ibm-plex-sans": "^5.3.0",
+    "@fontsource/ibm-plex-mono": "^5.3.0",
+    "astro": "^7.4.0",
+    "sharp": "^0.35.5",
+    "unist-util-visit": "^5.1.0"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "vfile": "^6.0.3"
+  }
+}