@hutusi/amytis 1.15.0 → 1.17.0

package/docs/CODE-BLOCKS.md

@@ -0,0 +1,238 @@
+# Code Blocks
+
+Amytis highlights code at **build time** with [Shiki](https://shiki.style/).
+The same pipeline runs for Markdown, MDX, and reStructuredText, so the
+authoring syntax is symmetric across formats: write a fence with metadata in
+Markdown/MDX, write directive options in rST, and the same features come out
+the other side.
+
+The features below are all opt-in — a plain `` ```ts `` fence still renders as a
+normal highlighted block.
+
+## Feature matrix
+
+| Feature | Markdown / MDX | rST |
+|---|---|---|
+| Line numbers | `` ```ts linenos `` | `:linenos:` |
+| Highlighted lines | `` ```ts {1,3-5} `` | `:emphasize-lines: 1,3-5` |
+| Title / filename bar | `` ```ts title="app.ts" `` | `:caption: app.ts` |
+| Override language | (set on the fence) | `:language: rust` |
+| Diff `+`/`-` backgrounds | `` ```diff `` | `.. code-block:: diff` |
+| Word-wrap toggle | header button (client) | header button (client) |
+
+All four metadata fields can be combined freely:
+
+````markdown
+```tsx title="components/CodeBlock.tsx" linenos {3,7-9}
+import { highlightToHast } from '@/lib/shiki';
+// ...
+```
+````
+
+```rst
+.. code-block:: tsx
+   :caption: components/CodeBlock.tsx
+   :linenos:
+   :emphasize-lines: 3,7-9
+
+   import { highlightToHast } from '@/lib/shiki';
+   ...
+```
+
+Both produce identical output: header bar with the filename + language label,
+a line-number gutter, and lines 3 and 7–9 highlighted.
+
+## Tabbed code groups
+
+Group adjacent fences into a tabbed widget. The mechanism is **CSS-only**
+(hidden `<input type="radio">` + `<label>` siblings + attribute selectors)
+— no JavaScript, no hydration cost. Keyboard navigation works for free via
+the browser's native arrow-key cycling between radios in the same group.
+
+**Markdown / MDX** — wrap fences in a `:::code-group` container directive
+from [`remark-directive`](https://github.com/remarkjs/remark-directive).
+Tab names come from a `[label]` token at the start of each fence's info
+string (Docusaurus convention). When `[label]` is absent, the language
+name is used as the tab name.
+
+````markdown
+:::code-group
+```bash [npm]
+npm install foo
+```
+```bash [yarn]
+yarn add foo
+```
+```bash [bun]
+bun add foo
+```
+:::
+````
+
+**rST** — use the custom `.. code-group::` directive wrapping nested
+`.. code-block::` blocks, each with a `:label:` option for the tab name:
+
+```rst
+.. code-group::
+
+   .. code-block:: bash
+      :label: npm
+
+      npm install foo
+
+   .. code-block:: bash
+      :label: yarn
+
+      yarn add foo
+```
+
+Both pipelines produce identical HTML and share the same CSS. Up to 10
+tabs per group are supported out of the box (CSS rules hardcoded for
+`data-idx="0"` through `data-idx="9"`); extend the rules in
+`src/app/globals.css` if you need more.
+
+### Tab icons
+
+When a tab label matches a known package manager, language name, or common
+config filename, an icon renders before the label automatically. Resolution
+cascade (first hit wins): exact label → filename → extension → language
+alias. See `src/lib/code-group-icons.ts` for the maps.
+
+Built-in icon keys: `npm`, `yarn`, `pnpm`, `bun`, `deno`, `typescript`,
+`javascript`, `python`, `rust`, `go`, `java`, `ruby`, `php`, `c`, `cpp`,
+`html`, `css`, `json`, `yaml`, `markdown`, `bash`, `docker`, `vite`,
+`react`, `vue`, `nextjs`, `node`, `tailwind`.
+
+A label that doesn't resolve renders without an icon (graceful fallback).
+To add an icon: extend the resolver in `src/lib/code-group-icons.ts` with
+the new key, then add a matching `.cg-tab[data-cg-icon="<key>"]::before`
+rule to `src/app/globals.css` with the SVG data URI.
+
+## Notation comments
+
+Six VitePress-style `[!code …]` markers can be embedded inline in any code
+block. They're written using the language's native comment syntax (the
+Shiki transformers detect `//`, `#`, `--`, `<!-- -->`, etc.):
+
+| Marker | Effect |
+|---|---|
+| `[!code focus]` | Dim every other line in the block; revert on `:hover` of the `<pre>` |
+| `[!code highlight]` | Same `.line.highlighted` style as the `{1,3-5}` fence-meta range syntax |
+| `[!code ++]` | Green-tinted line (same `.line.diff.add` as raw `+` in `diff` fences) |
+| `[!code --]` | Red-tinted line (same `.line.diff.remove` as raw `-` in `diff` fences) |
+| `[!code error]` | Red border + tint for error annotations |
+| `[!code warning]` | Amber border + tint for warning annotations |
+
+Example:
+
+````markdown
+```ts
+function login(user: string) {           // [!code focus]
+  const token = oldApi.auth(user)        // [!code --]
+  const token = newApi.auth({ user })    // [!code ++]
+  validate(token)                        // [!code highlight]
+  throwIfExpired(token)                  // [!code error]
+  if (!token.refreshable) warn()         // [!code warning]
+  return token
+}
+```
+````
+
+Notation comments and the meta-based features (`title="…"`, `linenos`,
+`{1,3-5}`) compose freely on the same fence.
+
+The four transformers (`transformerNotationFocus`, `transformerNotationErrorLevel`,
+`transformerNotationHighlight`, `transformerNotationDiff`) ship with the
+`@shikijs/transformers` package; see [`src/lib/shiki.ts`](../src/lib/shiki.ts)
+for where they're registered.
+
+## Supported languages
+
+**Any of Shiki's ~235 bundled languages works automatically** — including
+TypeScript, Python, Rust, Go, Bash, Make, Dockerfile, TOML, Kotlin, Swift,
+GraphQL, PHP, Lua, SQL, YAML, JSON, and many more. Display names and
+aliases come from Shiki's own metadata (e.g. ```ts``` / ```cts``` /
+```mts``` all resolve to TypeScript), so authors don't need to look up the
+canonical id.
+
+Grammars are loaded lazily on first use — there's no curated allowlist to
+maintain. Adding a new language to a post just works: write the fence with
+Shiki's id or any of its aliases.
+
+A small overlay also recognizes community-conventional aliases that aren't
+in Shiki's native alias table: `golang` → Go, `node` / `nodejs` →
+JavaScript, `obj-c` → Objective-C, `gnumakefile` / `bsdmakefile` → Make.
+To add more, extend `COMMUNITY_ALIASES` in `src/lib/shiki.ts`.
+
+Unknown languages **render as plaintext** with a one-line build-time
+warning (deduped per language). This is a deliberate exception to the
+`CLAUDE.md` "strict build over silent runtime failure" principle: at the
+fence-language layer, "typo" and "community alias" are indistinguishable
+from our side, and production deploys shouldn't fail on a single
+unhighlighted code block. Authors running a clean local build still see
+real typos in the warn output. For better highlighting on a known
+community name that Shiki doesn't ship as an alias, add an entry to
+`COMMUNITY_ALIASES` in `src/lib/shiki.ts`. To render unhighlighted code
+on purpose without the warn, use `plaintext` (or `text` / `txt` /
+`plain`).
+
+For the full list of supported language IDs and aliases, see Shiki's
+[bundle reference](https://shiki.style/languages) or:
+
+```bash
+node --input-type=module -e "import('shiki').then(m => console.log(m.bundledLanguagesInfo.map(l => l.id)))"
+```
+
+Shiki v4 is ESM-only, so the snippet uses dynamic `import()` rather than
+`require()`.
+
+## Diff fences
+
+When the language is exactly `diff`, lines starting with `+` get a green
+background and lines starting with `-` get a red background, on top of
+the normal token coloring. Lines like `+++` and `---` (diff headers) are
+intentionally NOT colored so they read as headers, not changes.
+
+## Word-wrap toggle
+
+Every block ships with two header buttons: `Copy` (the existing behavior)
+and `No wrap` / `Wrap`. The wrap toggle is per-block client state — it
+flips `data-wrap` on the block's root and CSS does the rest. There's no
+global default.
+
+## Theming
+
+Shiki runs in dual-theme mode with `github-light` and `github-dark`.
+Every token gets two CSS variables (`--shiki-light` and `--shiki-dark`),
+and `src/app/globals.css` picks one or the other based on the global
+`html.dark` class.
+
+To swap themes, edit `SHIKI_THEMES` in `src/lib/shiki.ts` and bump
+`RST_RENDERER_DISK_CACHE_VERSION` in `src/lib/rst-renderer.ts` so cached
+rST renders pick up the new theme (Markdown is highlighted on every
+render and doesn't need the bump).
+
+## How it works
+
+- **Markdown/MDX**: `MarkdownRenderer.tsx` parses fence meta (preserved via
+  the small `rehype-fence-meta.ts` plugin because `react-markdown` strips
+  `node.data` before invoking overrides). `CodeBlock` is an async server
+  component that calls `highlightToHast` and inlines the resulting HTML.
+- **rST**: `scripts/render-rst.py` rewrites each `literal_block` into an
+  opaque `<pre data-amytis-code …>` marker carrying option attributes.
+  `src/lib/shiki-rst.ts` walks the rendered HTML in `RstRenderer` and
+  replaces each marker with the same Shiki output.
+- The fallback rST parser (`src/lib/rst.ts`) converts directive options
+  into Markdown fence meta and routes through the MDX pipeline, so both
+  rST paths produce identical output.
+
+## Gotchas
+
+- The rST sanitize-html allowlist in `src/components/RstRenderer.tsx` must
+  permit `style` and `data-*` attributes on `pre`/`code`/`span`/`div`.
+  Stripping them silently kills syntax highlighting for rST while leaving
+  Markdown unaffected.
+- The Shiki highlighter is a singleton on `globalThis` — never instantiate
+  it per render. Loading WASM grammars takes ~1–2 s.
+- Mermaid blocks are short-circuited in `MarkdownRenderer.tsx` before
+  `CodeBlock` is reached; they never go through Shiki.

package/docs/CONTRIBUTING.md

@@ -17,6 +17,18 @@
 
 ## Writing Content
 
+For code-block features (line numbers, line highlighting, title bars, diff
+backgrounds, word-wrap toggle, notation comments, tabbed groups) and the
+per-format fence/directive syntax, see [`docs/CODE-BLOCKS.md`](./CODE-BLOCKS.md).
+
+For GitHub-flavored alert callouts (`> [!NOTE]`, `.. note::`, etc.) and the
+five supported alert types, see [`docs/ALERTS.md`](./ALERTS.md).
+
+Markdown links to other hosts (anything whose host differs from
+`siteConfig.baseUrl`) automatically render with a trailing `↗` icon and
+open in a new tab — don't write `<a target="_blank">` manually. Internal
+links, wikilinks, `mailto:`, and `tel:` are unaffected.
+
 ### Creating Posts
 
 Use the CLI to scaffold new content:
@@ -86,6 +98,10 @@ bun run new-from-images ./photos --title "Gallery"
 
 # Chat logs to flows
 bun run new-flow-from-chat
+
+# VuePress 2 book → Amytis book directory.
+# Full walkthrough at docs/guides/importing-vuepress-books.md.
+bun run sync-vuepress-book --source /path/to/dmla/docs --dest content/books/dmla
 ```
 
 ### Maintenance Tools
@@ -93,10 +109,19 @@ bun run new-flow-from-chat
 ```bash
 # Sync book chapters with files in the folder
 bun run sync-book
+bun run sync-book <slug>            # one book only
 
 # Bulk draft/publish a series
 bun run series-draft "my-series"
 bun run series-draft "my-series" --undraft
+
+# Add redirectFrom to series posts (for autoPaths / path migrations)
+bun run add-series-redirects                    # all series
+bun run add-series-redirects <series-slug>      # one series only
+bun run add-series-redirects --dry-run          # preview without writing
+
+# Reset build caches (when copy-assets or the image optimizer misbehave)
+bun run clean                       # removes .next, out, public/posts
 ```
 
 ## Running Tests

package/docs/DIGITAL_GARDEN.md

@@ -92,4 +92,4 @@ Related settings that shape the digital-garden experience live alongside that fl
 
 - `flows.recentCount`: controls how many flow entries appear on the homepage.
 - `pagination.flows` and `pagination.notes`: control listing page sizes.
-- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows.
+- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows. The three curated sections (`featured-posts`, `featured-series`, `featured-books`) also accept an `order` field — `'shuffle'` (default, daily-seeded permutation), `'date-desc'`, or `'date-asc'` — to choose how items inside the section are arranged.

package/docs/guides/README.md

@@ -0,0 +1,11 @@
+# Guides
+
+Focused, task-oriented walkthroughs for non-trivial workflows. Reference material
+lives in `docs/ARCHITECTURE.md`; commit conventions and the everyday command list
+live in `docs/CONTRIBUTING.md`.
+
+| Guide | Purpose |
+| --- | --- |
+| [Importing a VuePress 2 book](./importing-vuepress-books.md) | Mirror an external VuePress repo's `docs/` tree into an Amytis book directory, with sidebar conversion, math/container normalization, and idempotent re-runs. |
+
+Add new guides as `docs/guides/<topic>.md` and link them here.

package/docs/guides/importing-vuepress-books.md

@@ -0,0 +1,237 @@
+# Importing a VuePress book
+
+Amytis can host a VuePress book natively. `bun run sync-vuepress-book`
+copies the upstream `docs/` tree into a slug under `content/books/`, derives
+Amytis's nested-section book TOC from the VuePress sidebar config, and
+preserves any user-controlled fields you've added to the book's `index.mdx`.
+
+Both VuePress 2 and VuePress 1 sidebars are supported — the importer
+auto-detects the shape per entry, so a single config can mix `{ text, link }`
+(VP2) and `{ title, path }` (VP1) without configuration.
+
+The importer is idempotent — re-running mirrors the current state of the
+source (including upstream deletions). You should *not* edit chapter
+markdown files in the dest: they get overwritten on every sync. Customize
+the book's metadata in `index.mdx` (preserved) or extend the source repo.
+
+---
+
+## Prerequisites
+
+- The source must be a VuePress project (1.x or 2.x) where the docs root
+  contains a `.vuepress/` directory with a `config.js` or `config.mjs`.
+- `config.ts` is **not supported** — acorn (used to AST-extract the sidebar)
+  parses JS only. Compile to JS first (`tsc`, `bun build --no-bundle`, …) or
+  rename to `.mjs` if the config is pure ESM.
+- The destination directory under `content/books/<slug>/` may already exist
+  with a partial `index.mdx`; user-controlled frontmatter is preserved.
+
+## Quick start
+
+```bash
+bun run sync-vuepress-book \
+  --source /path/to/your-book/docs \
+  --dest   content/books/your-book
+
+# Positional shorthand:
+bun run sync-vuepress-book /path/to/your-book/docs content/books/your-book
+
+# Skip extra files alongside the built-in defaults:
+bun run sync-vuepress-book /path/to/docs content/books/foo --skip '*.bak,dist'
+
+# Then rebuild + preview locally:
+bun run build:dev
+bun dev
+```
+
+The script prints a one-line summary on completion:
+
+```
+[sync-vuepress-book] Done. 74 markdown files, 104 asset files copied, 61 chapters mapped.
+```
+
+It will also warn about anomalies it noticed in the sidebar — empty section
+placeholders, dropped meta-nav leaves (see [Conventions](#conventions)
+below), files filtered out by skip rules, etc.
+
+## Skip rules
+
+A VuePress repo's docs root often carries non-content files (lockfiles,
+package manifests, CI configs) that shouldn't land under
+`content/books/<slug>/`. Two flags control filtering:
+
+| Flag | Default | Effect |
+| --- | --- | --- |
+| `--skip-common` / `--no-skip-common` | on | Skip `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`, `bun.lock`, `bun.lockb`. |
+| `--skip <pattern,pattern,…>` | empty | Skip files/dirs whose **basename** matches any of the supplied glob patterns. `*` and `?` are supported. Repeatable. Applied to both files and directories anywhere in the tree. |
+
+Files filtered out by either rule are listed in the run summary. They're
+also pruned from the dest on subsequent re-syncs (the mirror logic applies
+to the same skip rules, so toggling `--no-skip-common` mid-stream brings
+the lockfiles back).
+
+## What the script does
+
+1. Locates `.vuepress/config.{js,mjs}` under `<source>`.
+2. AST-parses the file with acorn, walks the tree for the `sidebar:` array
+   wherever it lives (theme wrapper, plain export, etc.), and converts its
+   literals to a plain JS structure. Unsupported AST shapes throw — silent
+   drops would produce a half-correct TOC.
+3. Maps every VuePress sidebar item to one of:
+   - `{ title, id }` for a leaf. Accepted shapes:
+     - VP2: `{ text, link }`
+     - VP1: `{ title, path }` (no `children`)
+     - VP1: a bare string path (e.g. `'/intro/about-me'`) — the title is
+       read from the source file's frontmatter `title`, falling back to the
+       first H1, then a slug-derived fallback.
+   - `{ section, items, collapsible? }` for a group. Accepted shapes:
+     - VP2: `{ text, children, collapsible? }`
+     - VP1: `{ title, children, collapsable? }` (VP1's `collapsable` is
+       aliased to `collapsible`)
+   - A group entry that carries **both** `path` (VP1) or `link` (VP2) AND
+     `children` (a "section + index page" — common in VP1 books where
+     `/foo/` is the section's README) has its index page **promoted as the
+     first chapter** of the section. The promoted chapter's title is read
+     from the README's frontmatter or first H1, not from the section title,
+     so the sidebar doesn't show the section name twice.
+   - Mixed/unknown shapes are warned and skipped.
+4. Validates that every leaf's resolved chapter id has a real source file at
+   one of `<id>.md`, `<id>.mdx`, `<id>/README.md(x)`, or `<id>/index.md(x)`.
+   Throws and lists the missing files if any.
+5. **Mirrors** the source tree into `<dest>` (`fs.copyFileSync`):
+   - Copies every file except `.vuepress/`, `node_modules`, `.git`, and
+     dotfiles.
+   - Prunes any importer-managed dest file/dir whose path is no longer in
+     the source — re-running after an upstream rename or deletion is clean.
+   - Preserves `index.mdx` (regenerated separately, not mirrored) and any
+     dest dotfiles you added (`.gitkeep`, etc.).
+6. Rewrites `<dest>/index.mdx` with the new `chapters:` TOC, merging into
+   any existing frontmatter rather than replacing it. See
+   [User-controlled fields](#user-controlled-fields-in-indexmdx) below.
+
+## Conventions
+
+- Sidebar leaves whose id (case-insensitive, basename only) matches
+  `contents` or `SUMMARY` are dropped from the generated TOC. They're
+  VuePress/GitBook conventions for a hand-written table-of-contents page,
+  and Amytis's book landing page already renders one. The source files are
+  still copied so the dest layout matches upstream; they just aren't
+  reachable from the TOC.
+- Sections with `collapsible: false` (or VP1's `collapsable: false`) on the
+  VuePress side keep that hint — the Amytis sidebar honors it (forces the
+  section open).
+- A group whose VuePress entry has both `link`/`path` and `children` has
+  the index page promoted as the section's first chapter (see "Maps every
+  VuePress sidebar item …" above). Earlier versions dropped the link with
+  a warning; the current behavior is strictly more useful and matches the
+  upstream VuePress click-the-section-title UX.
+- Path normalization is identical for VP1 and VP2: leading `/` stripped,
+  trailing `/` stripped (so `/guide/` resolves to id `guide` and the file
+  is found via the `guide/README.md` or `guide/index.md` candidate), and
+  any `.md`/`.mdx` suffix stripped. Both build-time validation and the
+  runtime chapter resolver accept `<id>.md`, `<id>.mdx`, `<id>/index.md`,
+  `<id>/index.mdx`, `<id>/README.md`, `<id>/README.mdx`.
+
+## User-controlled fields in `index.mdx`
+
+The script's footprint on `index.mdx` is deliberately narrow:
+
+- **First sync** (no `index.mdx` exists yet): a stub is created with
+  `title` (from the VuePress config), today's `date`, `draft: false`,
+  `featured: false`, and the parsed `chapters:`. Plus a one-line prose
+  body identifying the upstream source. These defaults exist solely so
+  the book is loadable by the runtime's Zod schema out of the box.
+- **Every re-sync after that**: only `chapters:` is touched. Every other
+  frontmatter key, including ones you've added (`coverImage`, `excerpt`,
+  `authors`, `latex`, `showChapterExcerpt`, anything else) and any value
+  you've cleared (including intentionally-blank `date: ""`), is preserved
+  exactly. The prose body below the frontmatter is preserved too.
+
+In other words: edit `index.mdx` once after the first sync, then never
+worry about the script rewriting your choices.
+
+The handful of fields that matter for book rendering:
+
+| Field        | Notes |
+| --- | --- |
+| `title`      | Required by the runtime — keep something here. |
+| `excerpt`    | Optional one-liner shown on book listings. |
+| `date`       | Optional. |
+| `coverImage` | Optional. |
+| `featured`   | Show on the home page's featured strip. |
+| `draft`      | Hides the book from listings when `true`. |
+| `authors`    | Optional list. |
+| `latex`      | Set to `true` for math-heavy books to enable KaTeX globally for the book. |
+| `showChapterExcerpt` | Defaults to `false`. Set to `true` if you want each chapter's `excerpt` rendered as a subtitle under the chapter title; most chapters open with their own lede paragraph so the default suppresses it. |
+| `chapters`   | **Always rewritten** from the sidebar. |
+
+## What about VuePress-specific content?
+
+`MarkdownRenderer` quietly handles the syntax shapes the VuePress ecosystem
+uses, so you don't have to rewrite chapters by hand:
+
+- **`:::note` / `:::tip` / `:::warning` / `:::danger` / `:::info`** —
+  rewritten to Amytis's existing `<GithubAlert>` component. Custom titles
+  (e.g. `:::tip 智慧的疆界`) are preserved via `data-alert-title`.
+- **Mermaid fences** — `` ```mermaid `` blocks render via the existing
+  `<Mermaid>` client component. The `compact` modifier dmla uses is harmless
+  (it lives in fence meta, not the language tag).
+- **Inline `$$ ... $$` block math** — VuePress allows
+  `$$ \mathbf{A} = \begin{bmatrix}` openers and `\end{bmatrix} $$` closers
+  on the same line as the math body; `remark-math` requires `$$` to be on
+  its own line. A pre-processor (`normalizeVuepressBlockMath`) splits them
+  before parsing, preserving any list-item indent.
+- **Inter-chapter `[X](other.md)` links** — `remark-book-chapter-links`
+  rewrites these to canonical `/books/<slug>/<chapter-id>` URLs. Targets
+  outside the book throw; targets not in the TOC (work-in-progress chapters
+  the author commented out of the sidebar) warn and pass through unrewritten.
+- **CJK in math** — KaTeX's `unicodeTextInMathMode` warning is silenced via
+  `strict: 'ignore'`. Chinese-language math like `$输入$` or `$h_{隐藏状态}$`
+  renders without flooding the dev console.
+- **Custom Vue components** — `<Swiper>` / `<Slide>` / `<ClientOnly>` /
+  `<GlobalTOC>` / `<HomeHero>` / `<ChatDemo>` get passive overrides so
+  React doesn't warn about unknown HTML tags. Children pass through where
+  reasonable (slides stack vertically); UI-component nulls render nothing.
+- **Inline-styled `<img>` tags** — author-supplied `style` attributes
+  (typical for small social-media icons in author bios) are respected and
+  the image isn't pushed through `next/image` optimization.
+
+## Re-running
+
+Running the sync again against the same source/dest is the common case:
+
+```bash
+bun run sync-vuepress-book --source ... --dest ...
+```
+
+It is **safe** and **idempotent** so long as you haven't hand-edited the
+synced chapter `.md` files. The script:
+
+- Overwrites every chapter file from source.
+- Prunes importer-managed dest files whose path is not in the current source.
+- Re-derives `chapters:` from the current sidebar.
+- Preserves user-controlled `index.mdx` fields + body.
+
+After re-running, run `bun run build:dev` to regenerate the image-optimization
+output under `public/books/<slug>/` and the Pagefind search index.
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `[amytis] No VuePress config found …` | Source isn't a VuePress 2 docs root | Pass the parent of `.vuepress/`, e.g. `<repo>/docs`, not the repo root. |
+| `[amytis] Found config.ts …` error | TS config not supported | Compile to JS first, or rename to `.mjs` if pure ESM. |
+| `[amytis] N sidebar leaf chapters point to source files that do not exist` | Sidebar entry has no matching `.md` | Fix the sidebar in the VuePress config or write the missing file. |
+| `Could not locate a sidebar: [...] property` | Sidebar uses an unsupported shape | The walker only handles plain literal arrays/objects; a sidebar built by a function call won't work. Extract to a literal array. |
+| Chapter page 404s after sync | Chapter file moved/renamed upstream, but the dest dir still has the old file | This shouldn't happen now (mirror prunes deletions); if it does, rerun the sync and clear `.next` / `public/books/<slug>`. |
+| Stale image after upstream rename | Pagefind / Next image cache | `bun run clean && bun run build:dev`. |
+
+## Related
+
+- `scripts/sync-vuepress-book.ts` — the implementation.
+- `docs/ARCHITECTURE.md` — book schema, route map, and the markdown
+  pipeline plugins listed above.
+- `tests/integration/sync-vuepress-book.test.ts` — covers AST extraction,
+  mirror semantics, folder-index links, TS-config rejection, dotfile
+  preservation, the `contents` skip, and the VP1 sidebar shape (bare-string
+  children, `title`/`collapsable`, README promotion, `SUMMARY` drop).

package/eslint.config.mjs

@@ -1,13 +1,10 @@
 import { defineConfig, globalIgnores } from "eslint/config";
-import nextVitals from "eslint-config-next/core-web-vitals";
-import nextTs from "eslint-config-next/typescript";
+import nextPlugin from "@next/eslint-plugin-next";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import tseslint from "typescript-eslint";
 
 const eslintConfig = defineConfig([
-  ...nextVitals,
-  ...nextTs,
-  // Override default ignores of eslint-config-next.
   globalIgnores([
-    // Default ignores of eslint-config-next:
     ".next/**",
     "out/**",
     "build/**",
@@ -19,6 +16,21 @@ const eslintConfig = defineConfig([
     // Local Python renderer virtualenv
     ".venv-rst/**",
   ]),
+
+  ...tseslint.configs.recommended,
+
+  {
+    files: ["**/*.{js,jsx,mjs,ts,tsx,mts,cts}"],
+    plugins: {
+      "@next/next": nextPlugin,
+      "react-hooks": reactHooksPlugin,
+    },
+    rules: {
+      ...nextPlugin.configs.recommended.rules,
+      ...nextPlugin.configs["core-web-vitals"].rules,
+      ...reactHooksPlugin.configs.recommended.rules,
+    },
+  },
 ]);
 
 export default eslintConfig;