@hutusi/amytis 1.15.0 → 1.17.0

package/content/books/sample-book/index.mdx

@@ -6,6 +6,9 @@ coverImage: "/images/flowers.jpg"
 featured: true
 draft: false
 authors: ["Amytis"]
+# Render each chapter's excerpt as a subtitle under its title.
+# Default is false; enabled here so the template demonstrates the feature.
+showChapterExcerpt: true
 chapters:
   - part: "Part I: Getting Started"
     chapters:

package/content/posts/code-block-features-showcase.mdx

@@ -0,0 +1,223 @@
+---
+title: "Code Block Features Showcase"
+date: "2026-05-25"
+excerpt: "Walk through the advanced code-block features: line numbers, line highlighting, title bars, diff colors, word-wrap toggle, and plaintext fallback."
+category: "Showcase"
+tags: ["test", "code", "shiki"]
+authors: ["Amytis Team"]
+toc: true
+---
+
+The default Shiki pipeline applies build-time syntax highlighting with a
+dual `github-light` / `github-dark` theme. The features below are opt-in
+via fence metadata.
+
+## Title bar
+
+```ts title="src/app.ts"
+export const greet = (name: string) => `Hello, ${name}!`;
+```
+
+## Line numbers
+
+```python linenos
+def fib(n):
+    if n < 2:
+        return n
+    return fib(n - 1) + fib(n - 2)
+```
+
+## Highlighted lines
+
+```rust {2,4-6}
+fn main() {
+    let x = compute();
+    println!("{x}");
+    if x > 10 {
+        warn();
+        recover();
+    }
+}
+```
+
+## Title + line numbers + highlights combined
+
+```tsx title="components/CodeBlock.tsx" linenos {3,7-9}
+import { highlightToHast } from '@/lib/shiki';
+import { toHtml } from 'hast-util-to-html';
+import CodeBlockToolbar from './CodeBlockToolbar';
+
+export default async function CodeBlock({ language, children, title }) {
+  const hast = await highlightToHast(children, language, { title });
+  const html = toHtml(hast);
+  return (
+    <div className="cb-root">
+      {title && <span className="cb-title">{title}</span>}
+      <CodeBlockToolbar code={children} />
+      <div dangerouslySetInnerHTML={{ __html: html }} />
+    </div>
+  );
+}
+```
+
+## Diff with red/green backgrounds
+
+```diff
+-export const VERSION = "1.0";
++export const VERSION = "2.0";
+ export const NAME = "amytis";
+-export const STAGE = "alpha";
++export const STAGE = "beta";
+```
+
+## Word-wrap toggle
+
+Long lines in code blocks overflow horizontally by default — the block grows
+a scrollbar at the bottom. Click the **Wrap** button in any block's header
+to soft-wrap long lines onto multiple visual lines instead; click again to
+restore horizontal scrolling.
+
+```bash
+curl -X POST "https://api.example.com/v1/items?fields=id,name,description,createdAt,updatedAt&sort=createdAt:desc&limit=100&offset=0&filter[status]=active&filter[category]=blog&include=author,tags" -H "Authorization: Bearer YOUR_API_TOKEN_HERE" -H "Content-Type: application/json" -d '{"name":"example","description":"a sufficiently long single line to demonstrate the wrap toggle"}'
+```
+
+Try the **Wrap** button in the header above ↑ to see the long line collapse
+into multiple soft-wrapped lines.
+
+## Mermaid still works (regression check)
+
+```mermaid
+graph LR
+  A[Markdown] --> B[remark]
+  B --> C[rehype + Shiki]
+  C --> D[Static HTML]
+```
+
+## Tabbed code groups
+
+Group adjacent fences into a single tabbed widget by wrapping them in a
+`:::code-group` container directive. Tab names come from the `[label]`
+token after the language. The mechanism is pure CSS (radio inputs + sibling
+selectors) — zero JavaScript, zero hydration cost.
+
+When a tab label matches a known package manager, language, or common
+config filename, an icon appears automatically before the label. Resolution
+is handled by `resolveCodeGroupIcon` in `src/lib/code-group-icons.ts`.
+
+:::code-group
+```bash [npm]
+npm install amytis
+```
+```bash [yarn]
+yarn add amytis
+```
+```bash [pnpm]
+pnpm add amytis
+```
+```bash [bun]
+bun add amytis
+```
+:::
+
+Filename labels also resolve — e.g. `tsconfig.json`, `vite.config.ts`, or
+`Dockerfile`:
+
+:::code-group
+```json [tsconfig.json]
+{ "compilerOptions": { "target": "es2022", "module": "esnext" } }
+```
+```ts [vite.config.ts]
+import { defineConfig } from 'vite';
+export default defineConfig({ server: { port: 5173 } });
+```
+```dockerfile [Dockerfile]
+FROM node:20-alpine
+WORKDIR /app
+COPY . .
+RUN npm ci && npm run build
+```
+:::
+
+Tabs work across languages too — handy for showing the same algorithm in
+multiple implementations:
+
+:::code-group
+```ts [TypeScript]
+export function greet(name: string): string {
+  return `Hello, ${name}!`;
+}
+```
+```python [Python]
+def greet(name: str) -> str:
+    return f"Hello, {name}!"
+```
+```rust [Rust]
+fn greet(name: &str) -> String {
+    format!("Hello, {name}!")
+}
+```
+:::
+
+## Notation comments
+
+Annotate individual lines with `// [!code …]` comments. Six markers are
+supported — focus, diff, highlight, error, warning — using the language's
+native comment style (`//` in C-family, `#` in Python, `--` in SQL, etc.):
+
+```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
+}
+```
+
+`// [!code focus]` dims the rest of the block so the focused subset stands
+out; hover the block to reveal the dimmed lines. `// [!code error]` /
+`[!code warning]` tint the line with a colored left-border (red / amber).
+`[!code ++]` / `[!code --]` color individual lines without needing a
+`diff`-language fence.
+
+Notation comments work in **any** language — Python:
+
+```python
+def fib(n):
+    if n < 2: return n          # [!code focus]
+    return fib(n-1) + fib(n-2)
+```
+
+## GitHub-flavored alerts
+
+Add a `[!TYPE]` marker on the first line of a blockquote to render it as a
+GitHub-style callout. Five types are supported, each with its own color,
+icon, and label:
+
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+
+rST equivalents (`.. note::` / `.. tip::` / `.. important::` / `.. warning::`
+/ `.. caution::`) render with matching colors via docutils' admonition
+directives — same visual treatment across both pipelines.
+
+## Explicit plaintext
+
+```plaintext
+This block opts out of syntax highlighting entirely. Use `plaintext` (or its
+aliases `text`, `txt`, `plain`) for prose-like blocks where token coloring
+would be noisy or misleading. Unknown language names will fail the build.
+```

package/docs/ALERTS.md

@@ -0,0 +1,112 @@
+# Alerts (GitHub-flavored callouts)
+
+Amytis renders the five GitHub-flavored alert types as styled callouts.
+Both Markdown / MDX (`> [!TYPE]` blockquote markers) and rST (the built-in
+`.. note::` / `.. tip::` etc. directives) produce visually consistent
+output — same border color, same icon-less title bar for rST (docutils
+supplies the title), same per-type accent palette.
+
+## Markdown / MDX
+
+Start a blockquote with `[!TYPE]` on its own first line:
+
+```markdown
+> [!NOTE]
+> Highlights information that users should take into account, even when skimming.
+
+> [!TIP]
+> Optional information to help a user be more successful.
+
+> [!IMPORTANT]
+> Crucial information necessary for users to succeed.
+
+> [!WARNING]
+> Critical content demanding immediate user attention due to potential risks.
+
+> [!CAUTION]
+> Negative potential consequences of an action.
+```
+
+The marker is **case-insensitive** (`[!note]` works too). Body content
+keeps full Markdown — paragraphs, lists, links, inline code, even other
+code blocks.
+
+A blockquote without a recognized marker stays as a plain blockquote.
+An unknown type like `[!UNKNOWN]` also passes through unchanged.
+
+## reStructuredText
+
+rST uses docutils' built-in admonition directives. All five GitHub types
+have a docutils equivalent, plus a few aliases:
+
+```rst
+.. note::
+
+   Highlights information that users should take into account.
+
+.. tip::
+
+   Optional information to help a user be more successful.
+
+.. hint::
+
+   Also styled as a tip.
+
+.. important::
+
+   Crucial information necessary for users to succeed.
+
+.. warning::
+
+   Critical content demanding immediate user attention.
+
+.. attention::
+
+   Also styled as a warning.
+
+.. caution::
+
+   Negative potential consequences of an action.
+
+.. danger::
+
+   Also styled as a caution.
+```
+
+The CSS rules in `src/app/globals.css` apply the same `--alert-accent`
+color variable to docutils' `.admonition-note` / `.admonition-tip` /
+`.admonition-hint` / `.admonition-important` / `.admonition-warning` /
+`.admonition-attention` / `.admonition-caution` / `.admonition-danger`
+classes, so `> [!NOTE]` in MDX and `.. note::` in rST land at the same
+visual output.
+
+## Visual style
+
+- Per-type accent color drives the left border, the title bar text, and
+  a tinted background (8% accent over the page background).
+- Dark mode uses brighter accent variants matching GitHub Primer's
+  dark-tier alert colors.
+- MDX alerts use an inline SVG icon; rST admonitions skip the icon (docutils
+  doesn't emit one) but keep the colored title.
+
+## How it works
+
+- **MDX**: a small remark plugin at `src/lib/remark-github-alerts.ts`
+  detects the `[!TYPE]` marker, strips it from the blockquote, and routes
+  the node through a `<GithubAlert>` React server component
+  (`src/components/GithubAlert.tsx`). `remark-gfm` v4 does NOT include
+  the alert transform — it passes blockquotes through with the marker
+  intact — so the plugin is what makes this work.
+- **rST**: docutils' built-in admonition directives produce the
+  `<aside class="admonition admonition-<type>">` markup. The shared CSS
+  in `globals.css` matches both pipelines.
+
+## Gotchas
+
+- Don't rely on a blank line between the marker and body — `> [!NOTE]\n> body`
+  works; `> [!NOTE]\n>\n> body` also works.
+- The marker must be `[!TYPE]` *exactly* (square brackets, exclamation,
+  type). VitePress-style colon variants like `:::tip` aren't recognized.
+- Custom alert types beyond the five GitHub ones aren't supported. If you
+  need one, extend the regex in `remark-github-alerts.ts` and add a CSS
+  rule.

package/docs/ARCHITECTURE.md

@@ -94,11 +94,45 @@ src/app/
 
 ## 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`)
 
@@ -108,6 +142,15 @@ 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.
@@ -127,3 +170,253 @@ 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).
+
+#### Immersive reading mode
+
+Book chapters AND series posts support an "immersive reading" mode: a
+fullscreen overlay with a top bar, a content-type-specific sidebar on the
+left, and the article in a centred scrollable column. Entered two ways —
+the toggle button in the article header (chapter header for books, post
+header for series), or the secondary "Immersive reading" CTA on the book
+index (`/books/<slug>`) or series index (`/series/<slug>`), which links to
+the first chapter/post with `?immersive=1` appended.
+
+**Generic reader, content-type-specific shells.** The overlay
+(`src/components/ImmersiveReader.tsx`) and top bar
+(`src/components/ImmersiveReaderTopBar.tsx`) are content-type-agnostic —
+both take `rootHref` / `rootTitle` / `currentTitle` props plus a pre-rendered
+`sidebar` ReactNode. Two shells consume the reader:
+
+- `src/components/BookReadingShell.tsx` for chapters — passes
+  `<BookSidebar mode="fill" ...>` as the sidebar.
+- `src/components/PostReadingShell.tsx` for series posts — passes
+  `<SeriesList mode="fill" ...>`. The toggle is gated on `post.series`;
+  non-series posts don't see a useless button.
+
+**Layout boundaries.** The provider needs to survive client-side navigation
+between sibling items within a content unit. Three layout files mount it:
+
+- `src/app/books/[slug]/layout.tsx` — books reader (chapter-to-chapter).
+- `src/app/[slug]/layout.tsx` — series posts on autoPaths URLs
+  (`/<series-slug>/<post>`), which is the default.
+- `src/app/posts/layout.tsx` — series posts on default-path URLs
+  (`/posts/<slug>`), for sites with `series.autoPaths: false`.
+
+Each layout file is identical: wraps `{children}` in
+`<ImmersiveReadingProvider>` plus a `<Suspense>`-isolated
+`<ImmersiveReadingFlagHandler />`. The three layouts each mount independent
+provider instances — `enabled` state doesn't bleed between content types —
+but localStorage prefs are shared (same `amytis-reader-prefs` key), so a
+reader's font/theme/width choices carry across books and series.
+
+**State + persistence.** `src/components/ImmersiveReadingProvider.tsx` holds
+the context. Preferences (`fontSize`, `readingTheme`, `columnWidth`,
+`sidebarOpen`) persist to `localStorage` under `amytis-reader-prefs` via the
+helpers in `src/lib/immersive-reading-prefs.ts`; the read path is per-key
+defensive so schema drift or hand-edited values fall back to their default
+without discarding the whole blob. `enabled` and `prefsPanelOpen` are
+deliberately **not** persisted — entering the reader is a per-visit intent,
+not a preference.
+
+**`?immersive=1` URL flag.** `src/components/ImmersiveReadingFlagHandler.tsx`
+sits as a sibling of `{children}` inside each layout (wrapped in its own
+`<Suspense>`), reads the query param via `useSearchParams`, calls
+`provider.enter()`, then strips the flag via `router.replace`. The Suspense
+boundary is load-bearing — `useSearchParams` triggers a static-export bailout,
+so wrapping the provider instead would drag the chapter/post page out of
+static prerender.
+
+**Overlay anatomy** (`ImmersiveReader.tsx`, `position: fixed inset-0 z-40`):
+
+- `ImmersiveReaderTopBar` — sidebar toggle, breadcrumb (book/chapter or
+  series/post), `Aa` button, exit (✕). The header is `relative z-30` so its
+  `backdrop-blur-md` stacking context paints above article-area code blocks.
+- `ImmersiveReadingPrefsPopover` — anchored under the `Aa` button. Four
+  control groups with visual previews: font size (4 sizes, `A` letters at the
+  actual size), reading theme (Auto / Light / Sepia / Dark colour swatches —
+  Auto reads as a split light/dark gradient), column width (Narrow / Medium /
+  Wide / Full as stacked line-icons), and a "Reset to defaults" link at the
+  bottom (one-click, no confirmation). Dismisses on outside `pointerdown` or
+  ESC; ESC with the popover closed exits the reader.
+- Sidebar in `mode="fill"` — either `BookSidebar` or `SeriesList`, without
+  their page-mode positioning classes. Auto-collapsed below `lg`
+  (one-directional: never auto-opens on resize to wide).
+- Main scroll area — article centred at the column width the user picked
+  (`max-w-2xl` to `max-w-none`).
+
+**CSS scoping.** `html[data-immersive]` hides site chrome via the three stable
+hooks `data-site-nav` / `data-site-footer` / `data-reading-progress` —
+defense-in-depth (the fixed overlay covers them anyway). Reading-theme
+overrides are scoped to `[data-reader-overlay]` so they don't leak outside the
+reader; when `readingTheme === 'dark'` the overlay also gets Tailwind's `.dark`
+class so `dark:prose-invert` fires regardless of the underlying site theme.
+Shiki code blocks deliberately keep their normal theme.
+
+## 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.