@hutusi/amytis 1.14.0 → 1.16.0

package/docs/ARCHITECTURE.md

@@ -1,20 +1,21 @@
 # Architecture Overview
 
-Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX publishing across posts, series, books, flows, and notes.
+Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX publishing across posts, series, books, flows, and notes, with optional series-scoped rST support for legacy content.
 
 ## Core Stack
 
-- Framework: Next.js 16.1.6 + React 19
+- Framework: Next.js 16.2.1 + React 19
 - Runtime/tooling: Bun
 - Styling: Tailwind CSS v4 + CSS variables + `next-themes`
 - Content parsing: `gray-matter` + Zod validation in `src/lib/markdown.ts`
+- rST rendering: Python `docutils` bridge in `scripts/render-rst.py` plus normalization in `src/lib/rst-renderer.ts`
 - Search: Pagefind (`/pagefind/pagefind.js` loaded at runtime)
 - Tests: Bun test suites in `src/` and `tests/`
 
 ## Content Model
 
 - `content/posts/`: standalone posts (`.md/.mdx`) and folder posts (`index.mdx`)
-- `content/series/<slug>/`: series metadata (`index.mdx`) + series posts
+- `content/series/<slug>/`: series metadata (`index.mdx` / `index.md` / `README.mdx` / `README.md` / `index.rst` / `README.rst`) + series posts in the same format
 - `content/books/<slug>/`: book metadata + chapter files
 - `content/flows/YYYY/MM/DD.(md|mdx)`: daily flow entries
 - `content/notes/`: evergreen notes
@@ -27,6 +28,8 @@ Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX p
 3. Draft/future filtering and sorting are applied (based on `site.config.ts`).
 4. Route files consume typed helpers (`getAllPosts`, `getBookData`, `getAllFlows`, `getAllNotes`, etc.).
 5. `generateStaticParams()` precomputes dynamic routes for static export.
+6. Series content format is inferred from the series index file; ambiguous or mixed-format series fail fast during content loading.
+7. When `docutils` is available, rST files are rendered to HTML through the Python bridge; if the Python runtime is unavailable, Amytis falls back to the lightweight built-in rST compatibility path.
 
 ## Route Map (App Router)
 
@@ -75,21 +78,61 @@ src/app/
 ## URL Routing Rules
 
 - `next.config.ts` sets `output: "export"` and `trailingSlash: true`.
+- Series format is inferred from the index file:
+  - Markdown series: `index.md`, `index.mdx`, `README.md`, or `README.mdx`
+  - rST series: `index.rst` or `README.rst`
+- A series may not mix Markdown and rST content files; ambiguous or mixed layouts are treated as build errors.
 - Post URLs use `getPostUrl()` in `src/lib/urls.ts`:
   - Default: `/<posts.basePath>/<post.slug>` (basePath defaults to `posts`)
   - Series auto path: `/<series.slug>/<post.slug>` when `series.autoPaths` is enabled
   - Series override: `/<series.customPaths[seriesSlug]>/<post.slug>`
+- Legacy aliases declared in frontmatter `redirectFrom` are emitted as static redirect pages, so old URLs can continue resolving after a rename or path migration.
+- Dynamic route handlers validate whether a request is canonical or legacy, then either render the content or return `RedirectPage`.
 - Dynamic route params should return raw segment values from `generateStaticParams()` (do not pre-encode values).
 - Links should always target concrete paths, not route placeholders such as `/posts/[slug]`.
 - When moving series posts off the default posts path, `scripts/add-series-redirects.ts` updates frontmatter `redirectFrom` entries so static redirect pages can be generated.
 
 ## Key Components
 
-- Layout/navigation: `Navbar`, `Footer`, `Hero`, `FlowHubTabs`
-- Content renderers: `MarkdownRenderer`, `CodeBlock`, `Mermaid`
-- Post surfaces: `PostLayout`, `PostSidebar`, `PostCard`, `RelatedPosts`, `ShareBar`
-- Notes/flows discovery: `NoteSidebar`, `FlowContent`, `FlowCalendarSidebar`, `TagContentTabs`
-- Search/discovery: `Search`, `Pagination`, `KnowledgeGraph`
+Layout & navigation:
+
+- `Navbar`, `Footer`, `Hero` (configurable homepage hero with collapsible intro)
+- `LanguageSwitch` (i18n language selector), `ThemeToggle` (light/dark mode)
+- `FlowHubTabs`
+
+Content renderers:
+
+- `MarkdownRenderer` — MDX with GFM, KaTeX math, build-time syntax highlighting via Shiki, Mermaid
+- `CodeBlock` (async server component, calls Shiki) and `CodeBlockToolbar` (client: copy + word-wrap toggle), `Mermaid`
+- `CoverImage` — optimized image component with WebP support
+
+Post & series surfaces:
+
+- `PostLayout` / `SimpleLayout` — post page layouts with TOC, series sidebar, external links, comments
+- `PostList` — card-based post listing with thumbnails, metadata, excerpts, tags
+- `PostCard`, `PostSidebar`, `RelatedPosts`, `ShareBar`
+- `SeriesCatalog` — timeline-style listing with numbered entries and progress indicator
+- `SeriesSidebar` — series navigation sidebar with progress bar and color-coded states
+- `SeriesList` — mobile-optimized series navigation matching sidebar design
+- `TableOfContents` — sticky TOC with scroll tracking, reading progress, back-to-top
+- `HorizontalScroll` — scrollable container with navigation arrows for featured content
+
+Notes & flows:
+
+- `NoteSidebar`, `TagContentTabs`
+- `FlowContent` — client wrapper for flow pages with tag filtering state
+- `FlowCalendarSidebar` — calendar sidebar with date navigation, browse panel, clickable tag filters
+- `FlowTimelineEntry` — individual flow entry in timeline list
+
+Search & discovery:
+
+- `Search` — full-text search (Cmd/Ctrl+K) powered by Pagefind; type filter tabs (All/Post/Flow/Book), recent searches, keyboard navigation, debounced input, focus trap, ARIA, search syntax (`"phrase"`, `-exclude`)
+- `Pagination`, `KnowledgeGraph`
+
+Integrations:
+
+- `Comments` — Giscus or Disqus (theme-aware)
+- `Analytics` — Umami, Plausible, or Google Analytics
 
 ## Data Layer Highlights (`src/lib/markdown.ts`)
 
@@ -99,6 +142,25 @@ src/app/
 - Notes: `getAllNotes`, `getNoteBySlug`, `getNotesByTag`
 - Discovery: `buildSlugRegistry`, `getBacklinks`, `getAllTags`, `getAllAuthors`
 
+## Code Block Highlighting
+
+- Highlighter: **Shiki** (build-time, dual `github-light` / `github-dark` theme via CSS variables). See `docs/CODE-BLOCKS.md` for author-facing fence/directive metadata.
+- Singleton lives at `src/lib/shiki.ts` (`getHighlighter()`, cached on `globalThis` for HMR). It exposes `highlightToHast(code, language, opts)` and `parseFenceMeta(meta)`.
+- Transformers: `transformerMetaHighlight` from `@shikijs/transformers` plus three custom transformers in `src/lib/shiki.ts` for the line-numbers data attribute, the title data attribute, and raw-`diff` line backgrounds.
+- MDX/Markdown path: `MarkdownRenderer.tsx` → `rehype-fence-meta` (copies `node.data.meta` to a real `data-meta` HTML attribute so it survives `react-markdown`'s prop filtering and the `rehypeRaw` round-trip) → `CodeBlock` (async server component) → Shiki → inline HTML. Mermaid blocks are short-circuited before `CodeBlock` is reached.
+- rST path: `scripts/render-rst.py` rewrites every `literal_block` into a `<pre data-amytis-code …>` marker carrying option attributes (`data-language`, `data-line-numbers`, `data-highlight-lines`, `data-title`); `src/lib/shiki-rst.ts` walks the rendered HTML inside `RstRenderer` (async server component) and replaces each marker with Shiki output. The fallback rST parser routes through `rstToMarkdown` and lands in the MDX path — single highlighter, single source of truth.
+- Cache: `RST_RENDERER_DISK_CACHE_VERSION` in `src/lib/rst-renderer.ts` must be bumped whenever the docutils output shape or Shiki theme changes, otherwise stale cached entries in `.cache/rst-renderer/` keep rendering with the old markup.
+
+## rST Notes
+
+- Full-fidelity rST rendering depends on a Python environment with `docutils` (and ideally `pygments`) available.
+- `src/lib/rst-renderer.ts` uses `AMYTIS_RST_PYTHON` when set; otherwise it falls back to `python3`.
+- Top-of-document docinfo is parsed into Amytis metadata, but it is stripped from rendered article HTML so blog-style posts do not show duplicate author/version blocks above the content.
+- Supported legacy roles are normalized or degraded intentionally:
+  - `:doc:` resolves to local site URLs when the target exists in the imported content tree
+  - `:ref:` / `:numref:` prefer local anchors
+  - unresolved legacy roles degrade to readable inline HTML instead of docutils system-message blocks
+
 ## Build Pipeline
 
 1. `bun scripts/copy-assets.ts`: copy co-located media into `public/`
@@ -108,3 +170,172 @@ src/app/
 5. Pagefind indexing:
    - Production: `pagefind --site out` (writes to `out/pagefind`)
    - Dev build: `pagefind --site out --output-path public/pagefind`
+
+## Content Frontmatter
+
+Validated by Zod in `src/lib/markdown.ts` — invalid frontmatter throws at build time.
+
+### Posts
+
+```yaml
+---
+title: "Post Title"
+subtitle: "Optional subtitle line"  # Rendered below the title in italic
+date: "2026-01-01"
+excerpt: "Optional summary (auto-generated if omitted)"
+category: "Category Name"
+tags: ["tag1", "tag2"]
+authors: ["Author Name"]
+series: "series-slug"             # Link to a series
+draft: true                       # Hidden in production
+featured: true                    # Show in featured section
+pinned: true                      # Always shown in featured section; hero = most recent pinned
+coverImage: "./images/cover.jpg"  # Local path, external URL, or text placeholder
+latex: true                       # Enable KaTeX math
+toc: false                        # Hide table of contents
+layout: "simple"                  # Use simple layout (default: "post")
+externalLinks:                    # Links to external discussions
+  - name: "Hacker News"
+    url: "https://news.ycombinator.com/item?id=12345"
+  - name: "V2EX"
+    url: "https://v2ex.com/t/123456"
+redirectFrom:                     # Old URLs to redirect to this post (prefix changes only)
+  - /posts/my-old-slug
+  - /old-series/my-old-slug
+---
+```
+
+### Series (`content/series/[slug]/index.mdx`)
+
+```yaml
+---
+title: "Series Title"
+excerpt: "Series description"
+date: "2026-01-01"
+coverImage: "./images/cover.jpg"
+featured: true               # Show in featured series
+draft: true                  # Hidden in production (default: false)
+sort: "date-asc"             # 'date-asc' | 'date-desc' | 'manual'
+posts: ["post-1", "post-2"]  # Manual post ordering (optional)
+---
+```
+
+### Books (`content/books/[slug]/index.mdx`)
+
+A book's `chapters:` array accepts three item shapes (mix freely):
+
+```yaml
+---
+title: "Book Title"
+excerpt: "Book description"
+date: "2026-01-01"
+coverImage: "text:DG"             # Image path or text placeholder
+featured: true
+draft: false
+authors: ["Author Name"]
+chapters:
+  # 1. Bare chapter ref — top-level chapter with no grouping
+  - title: "Standalone Chapter"
+    id: "standalone"
+
+  # 2. Legacy "part" — single-level grouping
+  - part: "Part I: Getting Started"
+    chapters:
+      - title: "Chapter Title"
+        id: "chapter-file"        # Maps to chapter-file.mdx or chapter-file/index.mdx
+
+  # 3. "section" — recursive grouping with arbitrary nesting depth (≥ 2 layers)
+  - section: "机器学习数学基础"
+    collapsible: true             # Optional UI hint for the sidebar
+    items:
+      - section: "线性代数"
+        items:
+          - title: "引言：机器学习的语言"
+            id: "maths/linear/introduction"   # Slash-separated id → nested folder on disk
+          - title: "向量基础"
+            id: "maths/linear/vectors"
+      - section: "微积分"
+        items:
+          - title: "引言：变化与累积"
+            id: "maths/calculus/introduction"
+---
+```
+
+Chapter `id` values may contain `/` to map to nested folders. For id `maths/linear/introduction`,
+the loader resolves to the first existing file under `<bookDir>/maths/linear/introduction.{md,mdx}`
+or `<bookDir>/maths/linear/introduction/index.{md,mdx}`. Path traversal (`..`) is rejected.
+
+Per the strict-build invariant, `getBookData` throws if any chapter id in the TOC has no
+matching file on disk — silent skips are not allowed.
+
+#### Book-level `latex: true`
+
+Book frontmatter accepts an optional `latex: true` flag that enables KaTeX rendering for
+every chapter in the book without having to annotate each chapter file. Chapter-level
+`latex: true` still works and takes precedence. Math-heavy books (e.g. ML textbooks) should
+set the book-level flag rather than copy it onto every chapter.
+
+#### Book-level `showChapterExcerpt`
+
+Book frontmatter accepts an optional `showChapterExcerpt` flag (default `false`)
+controlling whether the chapter-page header renders the chapter's `excerpt` underneath
+the title. The default suppresses it because the common case is a chapter that opens
+with its own lede paragraph, and an excerpt line above it just duplicates that text.
+Set it to `true` on books where the excerpt is a distinct subtitle the author actually
+wants the reader to see. The excerpt is still used in metadata (OpenGraph, JSON-LD,
+search) regardless of this flag.
+
+#### Book-specific markdown extensions
+
+When `MarkdownRenderer` renders a book chapter (i.e. `bookContext` prop is set, which
+happens automatically inside `BookLayout`), two extra plugins fire:
+
+- **`remark-vuepress-containers`** — converts VuePress fenced containers
+  (`:::note`, `:::tip`, `:::important`, `:::warning`, `:::danger`, `:::info`) into the
+  same `<github-alert>` hast element that `remark-github-alerts` produces. Custom titles
+  (`:::tip 智慧的疆界`) are preserved via `data-alert-title`. A small string-level
+  preprocessor (`normalizeVuepressContainerSyntax`) normalizes `::: name [label]` →
+  `:::name[label]` so `remark-directive` (which only parses the space-less form) sees the
+  containers.
+- **`remark-book-chapter-links`** — rewrites relative `.md` / `.mdx` links to other
+  chapters into canonical `/books/<slug>/<chapter-id>[#fragment]` URLs. Resolution uses
+  the chapter's `sourcePath` (exposed by `getBookChapter`). Broken links (target chapter
+  id not in the TOC, or target outside the book directory) throw at build time.
+
+Mermaid diagrams in book chapters already work via the existing `Mermaid` component (any
+\`\`\`mermaid fenced block, with or without a `compact` modifier after the language tag).
+
+## Configuration Reference (`site.config.ts`)
+
+| Field | Notes |
+| --- | --- |
+| `nav` | Navigation links with weights |
+| `social` | GitHub, Twitter, email links for the footer |
+| `series.navbar` | Series slugs to show in the navbar dropdown |
+| `series.customPaths` | Per-series URL prefix, e.g. `{ 'weeklies': 'weeklies' }` → `/weeklies/[slug]` |
+| `pagination.posts`, `pagination.series` | Items per page |
+| `themeColor` | `'default' \| 'blue' \| 'rose' \| 'amber'` |
+| `hero` | Homepage hero title and subtitle |
+| `i18n` | Default locale and supported locales |
+| `featured.series` | Scrollable series: `scrollThreshold` (default 2), `maxItems` (default 6) |
+| `featured.stories` | Scrollable stories: `scrollThreshold` (default 1), `maxItems` (default 5) |
+| `analytics.providers` | Enabled providers, e.g. `['umami', 'google']`; `[]` disables |
+| `comments.provider` | `'giscus' \| 'disqus' \| null` |
+| `feed.format` | `'rss' \| 'atom' \| 'both'` |
+| `feed.content` | `'full' \| 'excerpt'` |
+| `feed.maxItems` | Max feed items (`0` = unlimited) |
+| `footer.bottomLinks` | Custom footer links (ICP, cookie policy); `text` accepts plain string or `{ en, zh }` |
+| `posts.basePath` | URL prefix for all posts (default `'posts'`) |
+| `posts.authors.default` | Fallback authors when a post has none in frontmatter |
+| `posts.authors.showInHeader` | Show author byline below post title (default `true`) |
+| `posts.authors.showAuthorCard` | Show author card at end of post (default `true`) |
+| `posts.excludeFromListing` | Series slugs whose posts are hidden from `/posts` listings |
+| `authors` | Per-author profiles: `bio`, `avatar`, `social[]` |
+
+### Config sync
+
+`site.config.ts` (this repo, i18n object form) and `site.config.example.ts`
+(shipped via `create-amytis`, plain strings, single-locale, optional features
+default disabled) must stay in sync. Any schema change to one must be mirrored
+in the other. Locale-aware fields use `{ en, zh }` in `site.config.ts` and
+plain strings in the example.

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:
@@ -47,6 +59,17 @@ bun run new-flow
 bun run new-series "My Series Name"
 ```
 
+Series are format-scoped:
+
+- Markdown series use `content/series/<slug>/index.mdx` or `index.md`
+- Markdown series may also use `README.mdx` or `README.md`
+- rST series use `content/series/<slug>/index.rst` or `README.rst`
+- Child posts inside the series must use the same format as the index file
+- Mixed Markdown and rST files in one series are treated as build errors
+- For full-fidelity rST rendering, install `docutils` (and `pygments` for code highlighting) in a Python environment available to the project
+- If needed, set `AMYTIS_RST_PYTHON=/absolute/path/to/python` so Amytis uses a specific interpreter
+- Without Python/docutils, Amytis falls back to a lightweight compatibility parser; that keeps loading/building working, but some legacy rST constructs will render with lower fidelity
+
 ### Creating Books
 
 Books are manually structured in `content/books/`.
@@ -75,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
@@ -82,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/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.