@hutusi/amytis 1.14.0 → 1.16.0

package/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:
-          bun-version: latest
+          bun-version: 1.3.11
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

package/.github/workflows/publish.yml

@@ -19,7 +19,7 @@ jobs:
       
       - uses: oven-sh/setup-bun@v1
         with:
-          bun-version: latest
+          bun-version: 1.3.11
       
       - run: bun install --frozen-lockfile
       
@@ -43,7 +43,7 @@ jobs:
       
       - uses: oven-sh/setup-bun@v1
         with:
-          bun-version: latest
+          bun-version: 1.3.11
       
       - run: bun install --frozen-lockfile
       

package/CHANGELOG.md

@@ -5,6 +5,48 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.16.0] - 2026-06-01
+
+### Added
+- **VuePress Book Pipeline**: Books are now first-class with nested chapter ids and TOCs, a catch-all chapter route, collapsible sections in the chapter sidebar, book-level LaTeX/math, VuePress `:::container` admonitions, and inter-chapter links. Includes a new `bun run sync-vuepress-book` importer that handles frontmatter-less chapters and stale `.md` references gracefully.
+- **Shiki Syntax Highlighting**: Replaced `react-syntax-highlighter`/Prism with a build-time Shiki pipeline across both Markdown/MDX and rST. Unknown fence languages now degrade to plaintext with a build-log warning instead of crashing the build, and any bundled Shiki language is lazy-loaded on demand.
+- **Code-Group Tabs**: New `:::code-group` (Markdown) and `.. code-group::` (rST) directives render fenced blocks as switchable tabs, with auto-detected icons for languages, package managers, and config files.
+- **Shiki Notation Comments**: Inline `// [!code focus]`, `[!code error]`, `[!code warning]`, `[!code highlight]`, and diff markers render with visual indicators inside code blocks.
+- **GitHub-Flavored Alert Blockquotes**: `> [!NOTE]`, `> [!TIP]`, `> [!IMPORTANT]`, `> [!WARNING]`, `> [!CAUTION]` render as styled callouts in both Markdown and rST (admonition visual parity).
+- **Reading Meta**: Word count appears alongside reading time on post and chapter headers, with Chinese localization (`5 分钟阅读`).
+- **External Link Affordance**: Outward-arrow icon on external links, opened in a new tab.
+- **Code Block Polish**: Real tab icons via Iconify for code-group headers, proper-case language labels, a more prominent highlighted-line background, and rST `:linenos:` / `:emphasize-lines:` / `:caption:` support.
+
+### Changed
+- **Mermaid Diagrams** now render frameless by default — no outer border, padding, background, or shadow. Diagram SVGs use the full column width.
+- **`showChapterExcerpt`** defaults to `false` on books; opt back in per-book.
+- **Markdown Rendering Fidelity**: Single-line `$$ x $$` block math now expands and parses as display math; block math centers via `.katex-display`; VuePress inline `<img>` styling is preserved through import; KaTeX `unicodeTextInMathMode` warnings (noise on CJK math labels) are scoped-silenced.
+- **Dependency Refresh**: TypeScript 5.9 → 6.0, ESLint 9 → 10 (config rewritten without `eslint-config-next`), Next.js + safe minor/patch sweep, `@types/node` 24 → 25, `pdf-to-img` 5 → 6.
+
+### Fixed
+- **Hydration Mismatches**: Locale-bound text in `TocPanel`, `PostNavigation`, `PostSidebar`, and `ShareBar` no longer logs a hydration error on first paint for users whose stored locale differs from `siteConfig.i18n.defaultLocale`. Mermaid's mutation-prone wrapper is likewise marked.
+- **Table Padding**: Restored horizontal padding on prose table cells (the earlier `:where()`-based override was silently stripped by Tailwind v4 / Lightning CSS; replaced with a plain descendant selector that survives compilation).
+- **rST Fallback Parser**: Added rendering for `.. figure::`, line blocks, admonitions (including custom `.. cnote::` with caption), `:doc:` / `:ref:` / `:numref:` roles; suppresses `.. toctree::` from rendered body; normalizes escaped whitespace in inline rST.
+- **React 19 Warnings**: Resolved `react-hooks/set-state-in-effect` warnings and silenced image-preload warnings for local images. Eager `CoverImage` variants are no longer deprioritized.
+- **Copy-Paste UX**: Stripped per-paragraph backgrounds on article copy to prevent "striping" when pasting into rich-text editors. Clipboard-API guard before `preventDefault`.
+- **Misc**: `<summary>` styled as an interactive link; code-group icon lookups via `Object.hasOwn`; shiki dedup state reset in `finally`; `<style>` element scoping for shiki output; book import edge cases (URI decode, Vue component warnings, fenced blocks in container normalizer, chapter image paths relative to parent dir).
+
+## [1.15.0] - 2026-04-12
+
+### Added
+- **First-Class rST Support**: Added robust reStructuredText post and series support through the Python/docutils pipeline, including README-based series indexes and better handling of legacy rST metadata and content structure.
+- **Legacy rST Link Resolution**: Added support for legacy `:doc:` references, including same-series and cross-series links, so migrated rST content can keep its internal navigation intact.
+
+### Changed
+- **rST Rendering Fidelity**: Improved rST rendering parity with Markdown for links, tables, code blocks, images, and general article presentation, making legacy content feel native inside Amytis.
+- **Series Ordering Accuracy**: Series listing pages now sort by the real newest post date in each series instead of assuming the first rendered post is the latest one.
+- **Build Performance**: Significantly reduced rebuild cost by caching rendered rST output, preserving nested image optimizer caches, tightening asset sync behavior, reducing generated image width buckets, and skipping Pagefind work when exported HTML is unchanged.
+
+### Fixed
+- **Legacy rST Edge Cases**: Fixed broken rST image rendering, restored docutils-based runtime rendering, accepted legacy single-digit date formats, improved adjacency/order handling for manually ordered rST series, and kept rST excerpts explicit when metadata omits them.
+- **Image Optimizer Compatibility**: Prevented broken optimized URLs for local `.avif` and `.webp` sources by bypassing `next-image-export-optimizer` for those files in shared image renderers.
+- **Create Amytis on Windows**: Fixed `create-amytis` scaffolding on Windows for releases containing Unicode paths by switching the Windows extraction path to ZIP + PowerShell. The scaffold package was also released separately as `create-amytis@0.1.2`.
+
 ## [1.14.0] - 2026-04-05
 
 ### Added

package/CLAUDE.md

@@ -1,231 +1,102 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code in this repo. Rules, gotchas, and pointers — not reference material.
 
-## Project Overview
+## Project
 
-Amytis is a static "digital garden" blog built with Next.js 15+ (App Router), React 19, and Tailwind CSS v4. Content is authored in MDX/Markdown files and statically generated at build time. Features include series support, multi-language (i18n), configurable themes, and comments integration.
+Amytis: static digital-garden blog (Next.js 16 App Router, React 19, Tailwind v4, static export). Content in MDX / Markdown (primary), rST (legacy support); everything resolves at build time. Package manager: bun.
 
-## Commands
+## Essential commands
 
 ```bash
-# Development
-bun dev                    # Start dev server at localhost:3000
-bun run lint               # Run ESLint
-
-# Testing
-bun test                   # Run all tests
-bun run test:unit          # Run unit tests (src/)
-bun run test:int           # Run integration tests
-bun run test:e2e           # Run end-to-end tests
-bun run test:mobile        # Run Playwright mobile compatibility tests (requires dev server)
-bun test path/to/file.test.ts  # Run a single test file
-
-# Build
-bun run build              # Full production build (copies assets, builds Next.js, optimizes images)
-bun run build:dev          # Development build (no image optimization, faster) — also regenerates Pagefind search index in public/pagefind/
-bun run clean              # Remove .next, out, public/posts directories
-
-# Deploy
-bun run deploy             # Deploy out/ to Linux/nginx server via rsync+sshpass (reads .env.local)
-
-# Content creation
-bun run new "Post Title"              # Create new post
-bun run new-series "Series Name"      # Create new series
-bun run new-from-pdf doc.pdf          # Create post from PDF
-bun run new-from-images ./photos      # Create post from image folder
-bun run new-flow                      # Create today's flow note
-bun run add-series-redirects                    # Add redirectFrom to all series posts (for autoPaths migration)
-bun run add-series-redirects <series-slug>      # Add redirectFrom to one series only
-bun run add-series-redirects --dry-run          # Preview without writing
-bun run new-flow-from-chat            # Import all new files from imports/chats/
-bun run sync-book                     # Sync chapters list for all books from disk
-bun run sync-book <slug>              # Sync chapters list for one book
+bun dev                 # dev server (Turbopack, http://localhost:3000)
+bun run lint            # ESLint
+bun test                # all tests
+bun run build           # production build (image optimization + Pagefind)
+bun run build:dev       # faster build; regenerates public/pagefind/ for search-in-dev
+bun run clean           # nuke .next, out, public/posts when caches misbehave
 ```
 
-## Design Principles
-
-- **Strict build over silent runtime failure.** This is a statically exported site — all misconfiguration must be caught at build time. Prefer `throw` in `generateStaticParams` and similar build-time functions over silent skips or `console.warn`. Examples: `validateSeriesAutoPaths` throws on slug collisions; `redirectFrom` alias conflicts should throw rather than silently producing broken redirects.
-
-## Architecture
-
-### Data Flow
-
-1. **Content source**: MDX/Markdown files in `content/posts/` and `content/series/`
-2. **Data layer**: `src/lib/markdown.ts` - reads files with Node `fs`, parses frontmatter with `gray-matter`, validates with Zod
-3. **Static generation**: Routes use `generateStaticParams` to pre-render at build time
-4. **Rendering**: `react-markdown` with remark/rehype plugins for GFM, math (KaTeX), syntax highlighting, and Mermaid diagrams
-
-### Key Files
-
-- `site.config.ts` - Site configuration (nav, social, pagination, themes, i18n, analytics, comments)
-- `src/lib/markdown.ts` - Data access layer with all content query functions
-- `src/lib/urls.ts` - Central URL helpers (`getPostUrl`, `getPostsBasePath`, `getSeriesCustomPaths`, etc.) — always use these instead of hardcoding `/posts/[slug]`
-- `src/lib/search-utils.ts` - Pure search utilities (URL type detection, date extraction, title cleaning, markdown stripping) shared by `Search` and the search index route
-- `src/app/globals.css` - Theme CSS variables and color palettes
-- `src/components/MarkdownRenderer.tsx` - MDX rendering with all plugins
-- `src/i18n/translations.ts` - Language strings for i18n
-
-### Route Structure
-
-- `/` - Homepage with hero, featured series, featured posts, latest writing
-- `/posts/[slug]` - Individual post pages
-- `/posts/page/[page]` - Paginated post listing
-- `/series` - All series overview
-- `/series/[slug]` - Single series with its posts
-- `/series/[slug]/page/[page]` - Series pagination
-- `/tags` - Tag cloud with post counts
-- `/tags/[tag]` - Posts filtered by tag
-- `/authors/[author]` - Posts filtered by author
-- `/archive` - Chronological listing grouped by year/month
-- `/books` - All books overview
-- `/books/[slug]` - Single book with chapter listing
-- `/books/[slug]/[chapter]` - Individual chapter page
-- `/flows` - Flow notes listing (paginated)
-- `/flows/page/[page]` - Paginated flow listing
-- `/flows/[year]` - Flows filtered by year
-- `/flows/[year]/[month]` - Flows filtered by month
-- `/flows/[year]/[month]/[day]` - Single flow detail page
-- `/[slug]` - Static pages (about, subscribe, etc.) and custom posts/series listing pages
-- `/[prefix]/[slug]` - Posts at custom URL prefixes (e.g. `/articles/my-post`, `/weeklies/my-post`)
-- `/[prefix]/page/[page]` - Paginated listing at custom URL prefixes
-
-### Content Structure
-
-**Posts** support two formats:
-- **Flat file**: `content/posts/my-post.mdx`
-- **Nested folder**: `content/posts/my-post/index.mdx` (allows co-located images in `./images/`)
-
-**Series** live in `content/series/[slug]/index.mdx` with optional `images/` folder for cover images.
-
-**Books** live in `content/books/[slug]/` with `index.mdx` for metadata and separate `.mdx` files per chapter. The `index.mdx` frontmatter defines chapter ordering with an optional parts structure.
-
-**Flows** (daily notes) live in `content/flows/YYYY/MM/DD.md` (or `.mdx`). Each flow has a date, title, excerpt, tags, and markdown content.
-
-Date-prefixed filenames (`2026-01-01-my-post.mdx`) extract dates automatically.
-
-## Config Files
-
-There are two config files that must be kept in sync:
-
-- **`site.config.ts`** — the live config for this repo (i18n enabled; locale-aware fields use `{ en: '...', zh: '...' }` objects)
-- **`site.config.example.ts`** — single-language starter template shipped via `create-amytis`; locale-aware fields use plain strings; optional features (books, flow) default to disabled
-
-**Rule:** Any schema change to `site.config.ts` (new field, renamed field, type change) must be mirrored in `site.config.example.ts`. Locale-aware values (`string | Record<string, string>`) should use plain strings in the example.
-
-## Configuration (`site.config.ts`)
-
-Key configuration options:
-- `nav` - Navigation links with weights
-- `social` - GitHub, Twitter, email links for footer
-- `series.navbar` - Series slugs to show in navbar dropdown
-- `series.customPaths` - Per-series custom URL prefix e.g. `{ 'weeklies': 'weeklies' }` → posts at `/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` - array of enabled providers: `['umami', 'google']`; `[]` disables analytics
-- `comments.provider` - 'giscus' | 'disqus' | null
-- `feed.format` - 'rss' | 'atom' | 'both'
-- `feed.content` - 'full' | 'excerpt'
-- `feed.maxItems` - max feed items (0 = unlimited)
-- `footer.bottomLinks` - custom links in the footer bottom bar (ICP, cookie policy, etc.); `text` accepts plain string or `{ en, zh }` locale map
-- `posts.basePath` - Custom URL prefix for all posts (default: `'posts'`); e.g. `'articles'` → posts at `/articles/[slug]`
-- `posts.authors.default` - Fallback authors when a post has none set 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` listing pages
-- `authors` - Per-author profiles: `bio`, `avatar` (image path), `social` (array of `{ image, description }`)
-
-## Content Frontmatter
-
-### 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; never shuffled away (hero = most recent pinned)
-coverImage: "./images/cover.jpg"  # Local or external URL
-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 that should redirect to this post (prefix changes only)
-  - /posts/my-old-slug
-  - /old-series/my-old-slug
----
-```
+Content-creation scripts, test layout, validate pipeline → `docs/CONTRIBUTING.md`.
 
-### 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)
----
-```
+## Architecture map
 
-### Books (`content/books/[slug]/index.mdx`)
-
-```yaml
----
-title: "Book Title"
-excerpt: "Book description"
-date: "2026-01-01"
-coverImage: "text:DG"           # Cover image or text placeholder
-featured: true                  # Show in featured books
-draft: false
-authors: ["Author Name"]
-chapters:
-  - part: "Part I: Getting Started"    # Optional part grouping
-    chapters:
-      - title: "Chapter Title"
-        id: "chapter-file"             # Maps to chapter-file.mdx or chapter-file/index.mdx
-  - part: "Part II: Advanced"
-    chapters:
-      - title: "Another Chapter"
-        id: "another-chapter"
----
-```
+Quick "where do routes live" lookup. Full reference: `docs/ARCHITECTURE.md`.
+
+- Standard routes follow folder names under `src/app/`: `/posts`, `/series`, `/tags`, `/notes`, `/books`, `/authors`, `/archive`, `/graph`, `/flows/[year]/[month]/[day]`.
+- **Top-level `[slug]` and `[slug]/[postSlug]`** resolve `redirectFrom` aliases and `series.customPaths` — highest-risk dynamic surface; touch with care.
+- Feeds at `feed.xml` / `feed.atom` / `all.xml` / `all.atom` / `flows/feed.{xml,atom}`; sitemap at `sitemap.ts`; search index at `search.json`.
+- Rendering pipeline lives in `src/lib/`: Shiki (`shiki.ts`, `shiki-rst.ts`), remark/rehype plugins (`remark-github-alerts`, `remark-wikilinks`, `remark-code-group`, `rehype-fence-meta`, `rehype-image-metadata`), redirects (`series-redirects.ts`), feeds/JSON-LD (`feed-utils.ts`, `json-ld.ts`).
+
+## Design principles
+
+- **Strict build over silent runtime failure.** Static export means misconfiguration must fail at build time. Use `throw` in `generateStaticParams` and similar — never silent skips or `console.warn`. Precedent: `validateSeriesAutoPaths` throws on slug collisions; `redirectFrom` alias conflicts (reserved slug or duplicate) should also throw, not produce broken redirects.
+  - **Exception**: fence-language resolution in `src/lib/shiki.ts` deliberately degrades to `plaintext` + a deduped `console.warn` instead of throwing. Authors can't reliably predict Shiki's alias coverage, and "typo" vs "legitimate community alias" are indistinguishable from our side, so production deploys shouldn't fail on a single unhighlighted code block. Real typos still surface via the warn output in local/CI build logs.
+- **Validate author input at build time; keep content portable.** Frontmatter via Zod; slug / redirect conflicts throw. Files on disk stay valid `.md` / `.mdx` / `.rst` — no Amytis-specific syntax that breaks other tools.
+
+## Integration-point rules (always go through X)
+
+- **URLs:** always `getPostUrl()` / `getPostsBasePath()` / `getSeriesCustomPaths()` from `src/lib/urls.ts`. Never hardcode `/posts/[slug]` — posts may live at `/articles/[slug]`, custom prefixes (`series.customPaths`), or under `posts.basePath`.
+- **Content reads:** always via `src/lib/markdown.ts` (`getAllPosts`, `getPostBySlug`, `getSeriesData`, etc.). Frontmatter validation belongs in its Zod schemas, not in route files.
+- **Search utilities:** pure helpers (URL type detection, date extraction, title cleaning, markdown stripping) live in `src/lib/search-utils.ts` and are shared by the `Search` component and the search-index route. Don't duplicate them.
+- **i18n strings:** add to `src/i18n/translations.ts`. Locale-aware config fields are `string | Record<string, string>`; resolve via `resolveLocale()` / `resolveLocaleValue()` from `src/lib/i18n.ts`.
+
+## Config sync
+
+`site.config.ts` (this repo — i18n object form, `{ en, zh }`) 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.
+
+## Gotchas (things Claude will get wrong on first try)
+
+- **`turbopackIgnore` on fs reads.** Any `fs.readFileSync()` path expression must be preceded by `/* turbopackIgnore: true */` (see `src/lib/markdown.ts`, `src/lib/rehype-image-metadata.ts`). Missing it causes incorrect bundling.
+- **No AVIF for `coverImage`.** Upstream bug in `next-image-export-optimizer` emits `.webp` files but a `srcset` pointing at `.avif` → 404 in prod. Use `.jpg` / `.png` / `.webp`. See `docs/TROUBLESHOOTING.md`.
+- **Unicode slugs.** Dynamic route pages call `safeDecodeParam()` and try decoded / raw / NFC / NFD variants — don't shortcut with bare `decodeURIComponent()` (it throws on malformed input). When touching dynamic routes, verify both ASCII and Unicode slugs.
+- **`generateStaticParams` returns raw values.** Don't `encodeURIComponent` route params; Next.js handles encoding. Don't link to placeholder routes like `/posts/[slug]` — always link to concrete URLs.
+- **Series format is locked.** A series index can be `index.md` / `.mdx` / `README.md` / `README.mdx` / `index.rst` / `README.rst` (first match wins). All child posts must match. Mixing formats is a build error.
+- **rST needs Python `docutils`.** Set `AMYTIS_RST_PYTHON=/path/to/python` if not on `$PATH`. Without it, falls back to a lower-fidelity built-in parser.
+- **Pagefind index.** `bun run build:dev` regenerates `public/pagefind/`; search returns stale results until you rerun it after content changes.
+- **`trailingSlash: true` is load-bearing.** Lets co-located post assets (`posts/slug/images/`) coexist with `posts/slug/index.html`. Don't flip it in `next.config.ts`.
+- **Shiki highlighter is a `globalThis` singleton.** Never instantiate it per render — `createHighlighter` loads Oniguruma WASM + grammars (~1–2 s). See `src/lib/shiki.ts`.
+- **rST sanitize-html allowlist must keep `style` + `data-*` on `pre`/`code`/`span`/`div`.** Stripping any of these silently kills Shiki output (monochrome text in prod, looks fine locally because dev rST isn't sanitized). See `src/components/RstRenderer.tsx`.
+- **Bump `RST_RENDERER_DISK_CACHE_VERSION` (`src/lib/rst-renderer.ts`) on highlighter-output changes.** Stale on-disk caches in `.cache/rst-renderer/` will serve old markup otherwise. Run `rm -rf .cache/rst-renderer` after pulling such a change.
+- **Fence meta needs `rehype-fence-meta` BEFORE `rehype-raw`.** `mdast-util-to-hast` stores fence meta on `node.data.meta`, which `rehype-raw` drops during HTML round-trip. The plugin copies it to a real `data-meta` attribute first. Order matters in `MarkdownRenderer.tsx`.
+- **Code-group tabs add `<input type="radio">` + `<label>` to the rST sanitize-html allowlist.** Keep the `transformTags` guard in `RstRenderer.tsx` that strips any `<input>` whose `type !== "radio"` — that's the defense against an rST author injecting password/file/etc. inputs through raw HTML.
+- **GitHub alerts (`> [!NOTE]`, etc.) need the custom `remarkGithubAlerts` plugin.** `remark-gfm` v4 does NOT transform `[!TYPE]` blockquotes — they pass through as plain blockquotes with the literal marker visible. The custom plugin in `src/lib/remark-github-alerts.ts` is what detects them and routes to `<GithubAlert>`. If a future remark-gfm adds native alert support, that's a regression to watch for (covered by an integration test).
+- **Single-line block math `$$ x $$` is silently inline.** `micromark-extension-math` (under `remark-math` v6) requires the `$$` markers on their own lines — single-line collapses to *inline* math (no `katex-display` wrapper, no centering, no display margin) and looks like a subtly under-styled formula. `src/lib/normalize-vuepress-math.ts` expands single-line `$$ x $$` to opener / body / closer before parsing, so authored content stays portable. If a chapter formula stops centering, suspect the normalizer's regex first.
+
+## Development workflow
+
+- **Don't push or open PRs unless asked.** Local commits are fine; anything touching the remote needs explicit go-ahead.
+- **Commit in focused slices.** Keep `bun run validate` green at each commit so the branch stays bisectable.
+- **Tests + docs in the same change.** Update `docs/ARCHITECTURE.md` / `docs/CONTRIBUTING.md` / `docs/TROUBLESHOOTING.md` alongside seam/workflow/invariant changes — not as a follow-up.
+- **Commits** follow Conventional Commits: `feat | fix | refactor | perf | chore | docs | test | release`. Subject under ~70 chars; body explains *why*.
+- **Branches:** `<type>/<kebab-slug>` matching commit prefixes.
+- **No Claude attribution.** Do not add `Co-Authored-By: Claude ...` trailers to commit messages or the `🤖 Generated with [Claude Code]` footer to PR descriptions. The default templates in the harness include both — strip them.
+
+## Verifying a change
+
+- **Default verify loop: `bun run lint && bun run test` only.** Stop here.
+- **Do NOT run `bun run build:dev` (or `bun run build` / `bun run validate`) unless the user asks OR it is genuinely needed.** It takes ~1–2 minutes (Turbopack compile + 800+ static pages + Pagefind index) and the cost adds up fast across many small steps. None of these are "needed" on their own: markdown pipeline edits, schema changes, route moves, branch tip, pre-PR readiness, "just to be safe."
+- "Genuinely needed" means lint+test **cannot** catch the failure mode you're worried about — e.g. a strict-build invariant that only fires during static export (a `throw` in `generateStaticParams`, a `redirectFrom` collision, a Zod-schema failure that only triggers on real content). If unsure, prefer asking over running.
+- `bun run validate` chains lint + test + build:dev; same rule — same bar.
+- Touched `src/lib/markdown.ts`, `src/lib/urls.ts`, or `site.config.ts`? Add an integration test under `tests/integration/`.
+- Touched any dynamic route? Verify both ASCII and Unicode slugs render.
+
+## Context compression hints
+
+When compressing history, preserve in priority order:
+
+1. **Build-time invariants touched** — strict-build/throw boundaries, Zod schemas, `site.config.ts` shape, helpers in `src/lib/urls.ts` / `src/lib/markdown.ts`.
+2. **Modified files and why** — file list with one-line reasons, not the diff.
+3. **Verification status** — `bun run lint && bun test` (and `build:dev` if run) pass/fail.
+4. **Cache version bumps** — `RST_RENDERER_DISK_CACHE_VERSION` etc.; easy to lose after compression.
+5. **Open TODOs and rollback notes.**
+6. **Tool output**: drop; keep pass/fail summary only.
+
+## Where to find more
 
-## Key Components
-
-- `PostLayout` / `SimpleLayout` - Post page layouts with TOC, series sidebar, external links, comments
-- `Hero` - Configurable homepage hero section with collapsible intro
-- `HorizontalScroll` - Scrollable container with navigation arrows for featured content
-- `PostList` - Card-based post listing with thumbnails, metadata, excerpts, and tags
-- `SeriesCatalog` - Timeline-style series post 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
-- `Search` - Full-text search (Cmd/Ctrl+K) powered by Pagefind (build-time index); features type filter tabs (All/Post/Flow/Book), recent searches, keyboard navigation (arrows + number keys), debounced input, body scroll lock, focus trap, ARIA accessibility, and search syntax tips (`"phrase"`, `-exclude`)
-- `TableOfContents` - Sticky TOC with scroll tracking, reading progress, and back-to-top
-- `MarkdownRenderer` - MDX rendering with GFM, math, syntax highlighting, diagrams
-- `CoverImage` - Optimized image component with WebP support
-- `Comments` - Giscus or Disqus integration (theme-aware)
-- `Analytics` - Umami, Plausible, or Google Analytics integration
-- `FlowContent` - Client wrapper for flow pages with tag filtering state management
-- `FlowCalendarSidebar` - Calendar sidebar with date navigation, browse panel, and clickable tag filters
-- `FlowTimelineEntry` - Individual flow entry in timeline list
-- `LanguageSwitch` - i18n language selector
-- `ThemeToggle` - Light/dark mode toggle
+- `docs/ARCHITECTURE.md` — route map, content model, components, data layer, frontmatter schemas, full configuration reference
+- `docs/CONTRIBUTING.md` — full command list, test layout, content-creation scripts
+- `docs/TROUBLESHOOTING.md` — known issues (AVIF, dev-mode browser-extension CSP/SharedStorage noise)
+- `docs/deployment.md` — production deploy steps
+- `docs/guides/` — task-oriented walkthroughs (e.g. `importing-vuepress-books.md`)
+- `site.config.ts` — live config (read it directly; don't infer from this file)

package/README.md

@@ -44,6 +44,8 @@ Further reading: [How to Get AI to Write Better Code](https://hutusi.com/weeklie
 - **Full-text Search:** Fast, static client-side search across all content (Cmd/Ctrl+K) powered by Pagefind.
 - **Structured Content:**
   - **Series:** Multi-part content organization with manual or automatic ordering.
+  - **Legacy rST Series:** A series can opt into reStructuredText by using `index.rst` or `README.rst`; mixed Markdown and rST files in the same series fail the build.
+  - **Docutils-backed rST Rendering:** When `docutils` is available, rST series render through the Python/docutils path instead of the lightweight fallback parser.
   - **Books:** Long-form content with explicit chapters, parts, and a dedicated reading interface.
   - **Notes:** Atomic, evergreen concepts for personal knowledge management.
   - **Flows:** Stream-style daily notes or micro-blogging for quick thoughts.
@@ -213,6 +215,8 @@ Amytis is built around Next.js static export with `output: "export"` and `traili
 - Posts default to `/<posts.basePath>/<slug>` and `posts.basePath` defaults to `/posts`.
 - If `series.autoPaths` is enabled, series posts move to `/<series-slug>/<post-slug>`.
 - If `series.customPaths` is configured, those custom prefixes override `autoPaths`.
+- Frontmatter `redirectFrom` entries are exported as static redirect pages so legacy URLs can keep working.
+- Prefer URL helpers over hardcoded post paths, because a canonical post URL may live under `/posts`, a series slug, or a custom prefix depending on config.
 - Before moving series posts off the default posts path, run `bun run add-series-redirects --dry-run` and then `bun run add-series-redirects` so legacy URLs still resolve.
 
 ## Writing Content
@@ -236,11 +240,39 @@ Create daily notes in `content/flows/YYYY/MM/DD.md` or `.mdx`.
 
 ### Series
 
-Create a directory in `content/series/<slug>/` with an `index.mdx`, then add posts as sibling files or folders.
+Create a directory in `content/series/<slug>/` with either:
+
+- `index.mdx` or `index.md` for a Markdown series
+- `index.rst` or `README.rst` for an rST series
+
+`README.mdx` and `README.md` are also accepted as Markdown series indexes. Then add posts as sibling files or folders using the same format as the series index. Mixed Markdown and rST files in one series are rejected at build time.
 
 - CLI: `bun run new-series "Series Name"`
 - You can also create a post directly inside an existing series with `bun run new "Post Title" --series <series-slug>`
 
+#### rST / docutils workflow
+
+For full-fidelity rST rendering, install `docutils` in a Python environment that the project can execute:
+
+```bash
+python3 -m pip install docutils pygments
+```
+
+If you want Amytis to use a specific interpreter, point `AMYTIS_RST_PYTHON` at it:
+
+```bash
+export AMYTIS_RST_PYTHON=/absolute/path/to/python
+```
+
+Current behavior:
+
+- `index.rst` or `README.rst` makes the whole series rST-only.
+- For rST series ordering, explicit `:posts:` metadata takes precedence. If `:posts:` is absent, Amytis uses simple local `.. toctree::` entry order from the series index. If neither exists, the series falls back to the existing date-based sort.
+- rST assets such as `.. image::` and `.. figure::` are resolved relative to the source file and rewritten to the site asset paths.
+- Supported legacy roles such as `:doc:`, `:ref:`, `:numref:`, `:math:`, and `:dtag:` are either rendered directly or degraded into readable inline output instead of docutils error blocks.
+- Top-of-file docinfo metadata is parsed into Amytis metadata, but it is not rendered at the top of blog-style article HTML.
+- If Python/docutils is unavailable, Amytis falls back to the lightweight built-in rST compatibility path. That path keeps series loading working, but it has lower fidelity than the docutils-backed renderer.
+
 ### Books
 
 Books are long-form structured content under `content/books/<slug>/`.

package/README.zh.md

@@ -44,6 +44,8 @@ Amytis 围绕一条从碎片想法到精炼知识的路径来帮助个人或组
 - **全文搜索:** 基于 Pagefind 的快速静态客户端全文搜索，支持 Cmd/Ctrl+K。
 - **结构化内容体系:**
   - **Series:** 支持手动或自动排序的多篇内容组织方式。
+  - **Legacy rST Series:** 当系列入口文件使用 `index.rst` 或 `README.rst` 时，该系列会按 reStructuredText 解析；同一系列中混用 Markdown 和 rST 会在构建时直接失败。
+  - **基于 docutils 的 rST 渲染：** 当环境中可用 `docutils` 时，rST 系列会走 Python/docutils 渲染路径，而不是轻量回退解析器。
   - **Books:** 支持明确章节、分部以及专用阅读界面的长篇内容。
   - **Notes:** 面向个人知识管理的原子化常青概念。
   - **Flows:** 用于快速记录想法的流式日记或微博客。
@@ -219,6 +221,8 @@ Amytis 基于 Next.js 静态导出构建，关键配置为 `output: "export"`
 - 文章默认路径为 `/<posts.basePath>/<slug>`，其中 `posts.basePath` 默认值为 `/posts`。
 - 启用 `series.autoPaths` 后，系列文章会移动到 `/<series-slug>/<post-slug>`。
 - 如果配置了 `series.customPaths`，则会以这些自定义前缀覆盖 `autoPaths`。
+- frontmatter 中的 `redirectFrom` 会在导出时生成静态跳转页，用于保留旧链接。
+- 不要硬编码文章路径，优先使用 URL helper，因为规范 URL 可能位于 `/posts`、系列 slug 或自定义前缀之下。
 - 在把系列文章从默认的 posts 路径迁走之前，先运行 `bun run add-series-redirects --dry-run`，再执行 `bun run add-series-redirects`，以确保旧链接仍然可访问。
 
 ## 内容写作
@@ -242,11 +246,39 @@ Amytis 基于 Next.js 静态导出构建，关键配置为 `output: "export"`
 
 ### Series
 
-在 `content/series/<slug>/` 下创建目录和 `index.mdx`，然后将系列文章作为同级文件或文件夹加入其中。
+在 `content/series/<slug>/` 下创建目录，并选择以下其中一种入口文件：
+
+- `index.mdx` 或 `index.md`，表示 Markdown 系列
+- `index.rst` 或 `README.rst`，表示 rST 系列
+
+`README.mdx` 和 `README.md` 也可作为 Markdown 系列入口。随后使用与入口文件一致的格式添加同级文章文件或子目录。同一系列中混用 Markdown 和 rST 会在构建时被拒绝。
 
 - CLI: `bun run new-series "Series Name"`
 - 也可以直接将文章创建到已有系列中: `bun run new "Post Title" --series <series-slug>`
 
+#### rST / docutils 工作流
+
+如果希望获得更完整的 rST 渲染效果，请在一个可执行的 Python 环境中安装 `docutils`：
+
+```bash
+python3 -m pip install docutils pygments
+```
+
+如果需要显式指定解释器，可设置 `AMYTIS_RST_PYTHON`：
+
+```bash
+export AMYTIS_RST_PYTHON=/absolute/path/to/python
+```
+
+当前行为：
+
+- `index.rst` 或 `README.rst` 会让整个系列进入 rST 模式。
+- 对于 rST 系列文章顺序，显式的 `:posts:` 元数据优先级最高；如果没有 `:posts:`，Amytis 会使用系列入口文件中简单本地 `.. toctree::` 条目的顺序；如果两者都没有，则回退到现有的基于日期排序。
+- `.. image::`、`.. figure::` 等资源路径会相对源文件解析，并重写为站点可用的静态资源路径。
+- `:doc:`、`:ref:`、`:numref:`、`:math:`、`:dtag:` 等常见 legacy role 会尽量直接渲染；无法完整支持时也会降级为可读的内联输出，而不是 docutils 报错块。
+- 文件顶部的 docinfo 元数据会被解析为 Amytis 元数据，但不会再渲染为文章顶部的作者/版本信息块。
+- 如果 Python/docutils 不可用，Amytis 会回退到内置的轻量 rST 兼容路径。这样仍可加载系列，但渲染保真度会低于 docutils 路径。
+
 ### Books
 
 书籍是位于 `content/books/<slug>/` 下的长篇结构化内容。

package/TODO.md

@@ -22,6 +22,15 @@
 - [ ] **Link Validator**: Script to check for broken internal wiki-links and external URLs.
 - [ ] **Content Porter**: Tool to import/export notes from Obsidian or Notion.
 - [ ] **Optimization**: Automatically compress and resize co-located images during build.
+- [ ] **Build Performance**: Profile `build:dev`, clean stale export/search outputs before indexing, and consider a lighter local build path that skips expensive full-site indexing when not needed.
+
+## 📚 rST Follow-up
+- [ ] **Fixture Coverage**: Add more compatibility fixtures from legacy rST series, including nested lists, tables, directives, images, and internal links.
+- [ ] **Parser Diagnostics**: Improve rST build errors with clearer file context, line numbers where possible, and actionable unsupported-syntax messages.
+- [ ] **Syntax Contract**: Document the exact supported rST subset and explicitly list unsupported or partial constructs.
+- [ ] **Asset & Link Handling**: Harden relative asset resolution and add validation for broken local rST links and image references.
+- [ ] **Reading Time**: Reuse the shared mixed-CJK reading-time rules for rST content so Chinese, Japanese, and Korean text are counted consistently.
+- [ ] **Advanced Constructs**: Evaluate the highest-value next rST features from real imported content, such as footnotes, simple tables, and selected directives.
 
 ## ✅ Completed Highlights
 - [x] **JSON-LD Structured Data**: `BlogPosting`, `Book`, and `Article` schemas for Google rich results.
@@ -33,3 +42,4 @@
 - [x] **Robust Engineering**: Zero hydration mismatches, Zod validation, and 64+ automated tests.
 - [x] **Refined UI**: High-contrast typography, four color palettes, and horizontal scroll featured sections.
 - [x] **Sub-features**: Newsletter/Subscribe page, Reading Progress, and Author Ecosystem.
+- [x] **Series-scoped rST Support**: Strict rST series detection, README-based indexes, Unicode-safe static params, and legacy redirect handling.