@hutusi/amytis 1.10.0 → 1.12.0

package/AGENTS.md

@@ -1,21 +1,27 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `tags`, `authors`, feeds, sitemap).
+- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `books`, `flows`, `notes`, `tags`, `authors`, feeds, graph, sitemap, custom `[slug]` routes).
 - `src/components/`: Reusable UI building blocks (cards, navigation, search, i18n/theme controls).
-- `src/lib/`: Content parsing and shared logic (`markdown.ts`, i18n helpers, rehype utilities).
-- `content/posts/`, `content/series/`: Markdown/MDX source content. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
+- `src/lib/`: Content parsing and shared logic (`markdown.ts`, feed helpers, URL helpers, rehype/remark utilities).
+- `content/`: Markdown/MDX source content for posts, series, books, notes, flows, and static pages. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
 - `tests/`: Integration/e2e/tooling suites; keep focused utility tests near source (example: `src/lib/markdown.test.ts`).
-- `scripts/`: Bun-based authoring/import tooling.
+- `scripts/`: Bun-based authoring/import/build tooling.
+- `imports/`: Local-only staging area for chat logs, PDFs, and image folders consumed by import scripts; see `imports/README.md`.
+- `packages/create-amytis/`: The `bun create amytis` scaffold CLI; keep its tests aligned with repo scaffolding behavior.
+- `site.config.ts` is the live site configuration; `site.config.example.ts` is the fuller reference template.
 
 ## Build, Test, and Development Commands
 - `bun install`: Install dependencies.
 - `bun dev`: Run local dev server at `http://localhost:3000`.
-- `bun run build`: Production export build (asset copy + Next build + image optimizer).
-- `bun run build:dev`: Build without export image optimization.
-- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`).
+- `bun run build`: Production export build (copy assets, generate graph, Next build, optimize images, generate Pagefind index in `out/pagefind`).
+- `bun run build:dev`: Build without export image optimization and generate the dev search index in `public/pagefind`.
+- `bun run build:graph`: Regenerate the knowledge graph data.
+- `bun run validate`: Run the recommended pre-PR validation sequence (`lint`, `test`, `build:dev`).
+- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`, `public/books`, `public/flows`).
 - `bun run lint`: Run ESLint.
-- `bun test` / `bun run test:unit` / `bun run test:int` / `bun run test:e2e`: Run all or scoped tests.
+- `bun test` / `bun run test:unit` / `bun run test:int` / `bun run test:e2e` / `bun run test:mobile`: Run all or scoped tests.
+- Content tooling: `bun run new`, `bun run new-weekly`, `bun run new-series`, `bun run new-note`, `bun run new-flow`, `bun run new-flow-from-chat`, `bun run new-from-pdf`, `bun run new-from-images`, `bun run import-obsidian`, `bun run import-book`, `bun run sync-book`, `bun run series-draft`, `bun run add-series-redirects`.
 
 ## Coding Style & Naming Conventions
 - Use TypeScript for app and utility code; MDX/Markdown for content.
@@ -27,12 +33,15 @@
 - Project uses `output: "export"` and `trailingSlash: true` in `next.config.ts`.
 - In `generateStaticParams()`, return raw segment values; do not pre-encode with `encodeURIComponent`.
 - Never link to route placeholders like `/posts/[slug]`; always link to concrete slugs (for example, `/posts/中文测试文章`).
+- Posts default to `/<posts.basePath>/<slug>`, but may also resolve through `series.autoPaths`, `series.customPaths`, and `[slug]/[postSlug]`; preserve URL helpers instead of hardcoding paths.
+- Before moving series posts away from the default posts path, run `bun run add-series-redirects --dry-run` and then `bun run add-series-redirects` so legacy URLs keep resolving.
 - When touching dynamic routes, verify both ASCII and Unicode paths.
 
 ## Testing Guidelines
 - Test framework: Bun (`bun:test`). File pattern: `*.test.ts`.
-- Add tests when changing slug resolution, content parsing, routing, or scaffolding scripts.
+- Add tests when changing slug resolution, content parsing, routing, feed generation, or scaffolding scripts.
 - Before PR: run `bun run lint && bun test && bun run build:dev`.
+- Search in local dev depends on the Pagefind output from `bun run build:dev`; regenerate it when changing content or search behavior.
 
 ## Commit & Pull Request Guidelines
 - Follow Conventional Commits used in history (`feat:`, `fix:`, `refactor:`, `docs:`, `release:`).

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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.12.0] - 2026-03-08
+
+### Added
+- **Series Auto Paths**: Added `series.autoPaths` so series posts can be served directly at `/<series-slug>/<post-slug>` without manual per-series path mapping.
+- **URL Migration Tooling**: Added `bun run add-series-redirects` with `--dry-run` and `--auto-paths` support to backfill `redirectFrom` entries before route migrations.
+- **Collections**: Added curated cross-series collections with dedicated data-layer support, listing surfaces, and integration test coverage.
+- **Static Page Comments**: Added per-category comment controls plus optional comments on book chapters, notes, and flows.
+- **Obsidian Importer**: Added `bun run import-obsidian` for recursive vault import with wikilink rewriting and relative-path handling.
+- **Mobile Coverage**: Added Playwright-based mobile compatibility testing and homepage/navigation assertions across real-device profiles.
+
+### Changed
+- **Wikilink Readability**: Wikilinks now prefer rendered note titles over raw slugs where metadata is available.
+- **Homepage Behavior**: Clicking the logo on the homepage now scrolls back to the top, and section spacing stays consistent when optional homepage blocks are disabled.
+- **Documentation**: Refreshed repository guidance, architecture notes, and release-facing docs to match current commands, routing rules, and import workflows.
+
+### Fixed
+- **Redirect Safety**: Prevented `redirectFrom` aliases from hijacking reserved routes or existing pages, including conflicting and single-segment alias cases.
+- **Custom Route Redirects**: Fixed renamed-slug redirects for `series.customPaths` and `[slug]/[postSlug]` routes.
+- **Collection Integrity**: Fixed duplicate collection entries, draft leakage in production, and prev/next navigation inconsistencies.
+- **Tag URL Consistency**: Normalized mixed-case tag URLs without losing display casing and removed duplicate counting from same-document tag variants.
+- **Unicode Note Routing**: Fixed dev-mode handling for percent-encoded Unicode note slugs.
+- **Mobile UX**: Improved narrow-viewport layout stability, tap-target sizing, and flaky mobile test behavior.
+
+## [1.11.0] - 2026-03-07
+
+### Changed
+- **Feed Output Quality**: RSS and Atom feeds now render Markdown content as HTML, include richer item metadata, and send explicit cache headers for static deployments.
+- **Metadata Consistency**: Consolidated image URL resolution so Open Graph and JSON-LD metadata use the same asset handling logic.
+- **Documentation Sync**: Updated the English and Chinese READMEs plus contributor guidance to reflect current scaffolding behavior, dev-search setup, and workspace instructions.
+
+### Fixed
+- **RSS Standards Compliance**: Corrected the RSS MIME type to `application/rss+xml` and improved RSS/Atom structure for better reader compatibility.
+- **Feed Metadata Fidelity**: Improved handling of author fields, item content, and image metadata across feed generation and social preview output.
+- **Post Page Polish**: Improved post page OG images, previous/next navigation consistency, and TOC indentation.
+- **Book Link Consistency**: Standardized book links to use the shared URL helper.
+
+### Docs
+- **Developer Notes**: Added inline documentation for `getFeedItems()` behavior and configuration handling.
+- **Repository Instructions**: Refreshed repository-level agent instructions to match the current workspace layout and release workflow.
+
 ## [1.10.0] - 2026-03-02
 
 ### Added

package/CLAUDE.md

@@ -18,6 +18,7 @@ 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
@@ -34,11 +35,18 @@ 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
 ```
 
+## 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
@@ -96,6 +104,15 @@ bun run sync-book <slug>              # Sync chapters list for one book
 
 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:
@@ -109,8 +126,12 @@ Key configuration options:
 - `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.provider` - 'umami' | 'plausible' | 'google' | null
+- `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)
@@ -125,6 +146,7 @@ Key configuration options:
 ```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"
@@ -143,6 +165,9 @@ externalLinks:             # Links to external discussions
     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
 ---
 ```
 

package/README.md

@@ -6,7 +6,7 @@
 
 [**Live Demo**](https://amytis.vercel.app/)
 
-![Amytis Screenshot](public/screenshot.png)
+![Amytis Screenshot](public/images/amytis-screenshot.jpg)
 
 ## The Knowledge Ladder
 
@@ -50,9 +50,13 @@ Each stage builds on the previous one, so your garden can evolve naturally.
   - Co-located assets: keep images inside post folders (`./images/`).
   - Date-prefixed filenames: `2026-01-01-my-post.mdx`.
   - Draft support for posts, series, books, and flows.
+- **Author Ecosystem:** Per-author profile pages with bio, avatar, and social links. Posts are filterable by author; an optional author card appears at the end of each post.
 - **Performance & SEO:**
   - Fully static export with optimized WebP images.
-  - Native sitemap and RSS feed generation.
+  - Open Graph and Twitter card metadata for every content type.
+  - JSON-LD structured data (`BlogPosting`, `Book`, `Article`) for Google rich results.
+  - RSS/Atom feed with configurable format (`rss` | `atom` | `both`) and content depth (`full` | `excerpt`).
+  - Feed auto-discovery links in `<head>`, native sitemap generation.
   - Multilingual reading time estimate (supports Latin and CJK).
 - **Integrations:**
   - Analytics: Umami, Plausible, or Google Analytics.
@@ -71,6 +75,20 @@ Each stage builds on the previous one, so your garden can evolve naturally.
 
 ## Quick Start
 
+### New Project (Recommended)
+
+Scaffold a new Amytis site with one command:
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+The scaffold command downloads the latest tagged Amytis release, installs dependencies, and patches `site.config.ts` and `package.json` with your project metadata.
+
+### Clone & Run
+
 1. **Install Dependencies:**
    ```bash
    bun install
@@ -82,6 +100,8 @@ Each stage builds on the previous one, so your garden can evolve naturally.
    ```
    Visit [http://localhost:3000](http://localhost:3000).
 
+   > **Search in dev:** the Pagefind index is generated during `bun run build:dev`. Run it once before testing Cmd/Ctrl+K locally, and re-run it after content changes.
+
 3. **Build for Production (Static Export):**
    ```bash
    bun run build
@@ -99,6 +119,7 @@ Each stage builds on the previous one, so your garden can evolve naturally.
 ## Core
 bun dev
 bun run lint
+bun run build:graph
 bun run validate
 
 ## Build & Deploy
@@ -112,9 +133,11 @@ bun test
 bun run test:unit
 bun run test:int
 bun run test:e2e
+bun run test:mobile
 
 ## Create Content
 bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
 bun run new-series "Series Name"
 bun run new-note "Concept"
 bun run new-flow
@@ -123,9 +146,11 @@ bun run new-flow
 bun run new-from-pdf ./doc.pdf
 bun run new-from-images ./photos
 bun run new-flow-from-chat
+bun run import-obsidian
 bun run import-book
 bun run sync-book
 bun run series-draft "series-slug"
+bun run add-series-redirects --dry-run
 ```
 
 ### Importing Chat Logs to Flows
@@ -141,7 +166,7 @@ Import history is stored in `imports/chats/.imported`.
 
 ## Configuration
 
-All site settings are managed in `site.config.ts`:
+Primary site settings live in `site.config.ts`. `site.config.example.ts` is the reference template used by the scaffold and is useful when reviewing new options:
 
 ```typescript
 export const siteConfig = {
@@ -161,27 +186,66 @@ export const siteConfig = {
 };
 ```
 
+High-impact areas to customize first:
+
+- Site identity: `title`, `description`, `baseUrl`, `ogImage`, `logo`
+- Navigation and footer: `nav`, `footer`, `subscribe`, `social`
+- Content behavior: `posts.basePath`, `posts.includeDateInUrl`, `series.autoPaths`, `series.customPaths`
+- Homepage composition: `hero`, `homepage.sections`
+- Integrations: `analytics`, `comments`, `feed`, `i18n`
+
+For static hosting behind nginx, start from `nginx.conf.example`.
+
+## Static Export Routing Rules
+
+Amytis is built around Next.js static export with `output: "export"` and `trailingSlash: true`.
+
+- In `generateStaticParams()`, return raw segment values. Do not pre-encode with `encodeURIComponent`.
+- Link to concrete URLs such as `/posts/中文测试文章`, not route placeholders like `/posts/[slug]`.
+- 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`.
+- 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
 
 ### Posts
 
 Create `.md` or `.mdx` files in `content/posts/`.
 
+- Flat file: `content/posts/my-post.mdx`
+- Date-prefixed file: `content/posts/2026-01-01-my-post.mdx`
+- Folder post with co-located media: `content/posts/my-post/index.mdx` plus `content/posts/my-post/images/*`
+- CLI: `bun run new "Post Title"` or `bun run new "Post Title" --folder`
+
 ### Flows
 
-Create daily notes in `content/flows/YYYY/MM/DD.mdx` or `content/flows/YYYY/MM/DD/index.mdx`.
+Create daily notes in `content/flows/YYYY/MM/DD.md` or `.mdx`.
+
+- CLI: `bun run new-flow` creates today’s entry
+- Chat import: put exports in `imports/chats/` and run `bun run new-flow-from-chat`
 
 ### Series
 
-Create a directory in `content/series/` with an `index.mdx`.
+Create a directory in `content/series/<slug>/` with an `index.mdx`, then add posts as sibling files or folders.
+
+- 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>`
 
 ### Books
 
-Books are for long-form, structured content. Create a directory in `content/books/`.
+Books are long-form structured content under `content/books/<slug>/`.
+
+- Keep book metadata in `index.mdx`
+- Add chapter files beside it, for example `introduction.mdx` or `setup.mdx`
+- Use `bun run import-book` and `bun run sync-book` for book-oriented workflows
 
 ### Notes
 
-Create evergreen notes in `content/notes/` (e.g., `concept.mdx`). Use `[[wiki-links]]` to connect them.
+Create evergreen notes in `content/notes/` (for example `concept.mdx`). Use `[[wiki-links]]` to connect them.
+
+- CLI: `bun run new-note "Concept"`
+- Unicode slugs are supported intentionally for notes and posts where needed
 
 ## Project Structure
 
@@ -194,7 +258,10 @@ amytis/
     notes/              # Digital garden notes
     flows/              # Daily notes (YYYY/MM/DD)
     about.mdx           # Static pages
+  docs/                 # Architecture, deployment, troubleshooting
+  imports/              # Local-only input files for import scripts
   public/               # Static assets
+  scripts/              # Bun authoring/build/import tooling
   src/
     app/                # Next.js App Router pages
       books/            # Book routes
@@ -204,6 +271,9 @@ amytis/
     components/         # React components
     lib/
       markdown.ts       # Data access layer
+  tests/                # Unit, integration, e2e, tooling tests
+  packages/
+    create-amytis/      # `bun create amytis` scaffold CLI
   site.config.ts        # Site configuration
 ```
 
@@ -213,6 +283,7 @@ amytis/
 - [Deployment Guide](docs/deployment.md)
 - [Digital Garden Guide](docs/DIGITAL_GARDEN.md)
 - [Contributing Guide](docs/CONTRIBUTING.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
 
 ## License
 

package/README.zh.md

@@ -6,7 +6,7 @@
 
 [**在线演示**](https://amytis.vercel.app/)
 
-![Amytis 截图](public/screenshot.png)
+![Amytis 截图](public/images/amytis-screenshot.jpg)
 
 ## 知识阶梯
 
@@ -43,9 +43,13 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
   - 自动系统主题检测（明/暗）
   - 四套配色主题：default、blue、rose、amber
   - 吸顶目录与阅读进度跟踪
+- **作者生态**：每位作者有独立主页，包含简介、头像与社交链接。文章支持按作者筛选，并可在文末显示作者卡片。
 - **性能与 SEO**：
   - 全静态导出与 WebP 优化
-  - 自动 sitemap 与 RSS
+  - 每种内容类型均有完整的 Open Graph 与 Twitter Card 元数据
+  - JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体搜索结果
+  - RSS/Atom 订阅源，格式（`rss` | `atom` | `both`）与内容深度（`full` | `excerpt`）可配置
+  - `<head>` 自动注入 Feed 发现链接，原生 sitemap 生成
   - 支持 Latin/CJK 的多语言阅读时长估算
 - **集成能力**：
   - 统计：Umami / Plausible / Google Analytics
@@ -62,6 +66,20 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
 
 ## 快速开始
 
+### 新建项目（推荐）
+
+一条命令创建新的 Amytis 站点：
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+该脚手架会下载最新发布版 Amytis，自动安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
+
+### 克隆运行
+
 1. **安装依赖**
    ```bash
    bun install
@@ -73,6 +91,8 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
    ```
    打开 [http://localhost:3000](http://localhost:3000)。
 
+   > **本地搜索说明：** Pagefind 索引是在执行 `bun run build:dev` 时生成的。本地测试 Cmd/Ctrl+K 前先运行一次；内容更新后也需要重新生成。
+
 3. **生产构建（静态导出）**
    ```bash
    bun run build
@@ -90,6 +110,7 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
 ## Core
 bun dev
 bun run lint
+bun run build:graph
 bun run validate
 
 ## Build & Deploy
@@ -103,9 +124,11 @@ bun test
 bun run test:unit
 bun run test:int
 bun run test:e2e
+bun run test:mobile
 
 ## Create Content
 bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
 bun run new-series "Series Name"
 bun run new-note "Concept"
 bun run new-flow
@@ -114,9 +137,11 @@ bun run new-flow
 bun run new-from-pdf ./doc.pdf
 bun run new-from-images ./photos
 bun run new-flow-from-chat
+bun run import-obsidian
 bun run import-book
 bun run sync-book
 bun run series-draft "series-slug"
+bun run add-series-redirects --dry-run
 ```
 
 ### 导入聊天记录到 Flows
@@ -132,15 +157,37 @@ bun run new-flow-from-chat
 
 ## 配置
 
-所有站点配置集中在 `site.config.ts`。
+主要站点配置集中在 `site.config.ts`，`site.config.example.ts` 则是更完整的参考模板，适合查看可选项和默认写法。
+
+优先关注这些配置区块：
+
+- 站点信息：`title`、`description`、`baseUrl`、`ogImage`、`logo`
+- 导航与页脚：`nav`、`footer`、`subscribe`、`social`
+- 内容路由：`posts.basePath`、`posts.includeDateInUrl`、`series.autoPaths`、`series.customPaths`
+- 首页结构：`hero`、`homepage.sections`
+- 集成能力：`analytics`、`comments`、`feed`、`i18n`
+
+如果你部署到 nginx，可直接从 `nginx.conf.example` 开始调整。
+
+## 静态导出路由规则
+
+Amytis 基于 Next.js 静态导出，核心约束是 `output: "export"` 和 `trailingSlash: true`。
+
+- 在 `generateStaticParams()` 中返回原始路径片段，不要手动用 `encodeURIComponent`
+- 链接必须指向真实路径，例如 `/posts/中文测试文章`，不要写 `/posts/[slug]`
+- 文章默认路径是 `/<posts.basePath>/<slug>`，其中 `posts.basePath` 默认值为 `/posts`
+- 启用 `series.autoPaths` 后，系列文章会切换到 `/<series-slug>/<post-slug>`
+- 配置了 `series.customPaths` 时，会优先使用自定义前缀覆盖 `autoPaths`
+- 如果准备把系列文章从默认 `/posts/...` 路径迁走，先执行 `bun run add-series-redirects --dry-run`，确认后再执行 `bun run add-series-redirects`
 
 ## 内容写作
 
-- **Posts**：创建到 `content/posts/`
-- **Flows**：创建到 `content/flows/YYYY/MM/DD.mdx`（或文件夹模式）
-- **Series**：创建 `content/series/<slug>/index.mdx`
-- **Books**：创建到 `content/books/<slug>/`
-- **Notes**：创建到 `content/notes/`，支持 `[[wiki-links]]`
+- **Posts**：写入 `content/posts/`，支持单文件、日期前缀和文件夹模式。文件夹模式可将图片放在同目录的 `images/` 中。CLI：`bun run new "Post Title"` 或 `bun run new "Post Title" --folder`
+- **Flows**：写入 `content/flows/YYYY/MM/DD.md` 或 `.mdx`。CLI：`bun run new-flow`
+- **Series**：创建 `content/series/<slug>/index.mdx`，系列内文章可作为同级文件或子目录。CLI：`bun run new-series "Series Name"`
+- **Books**：写入 `content/books/<slug>/`，通常用 `index.mdx` 存元数据，其余章节文件与其并列
+- **Notes**：写入 `content/notes/`，支持 `[[wiki-links]]`。CLI：`bun run new-note "Concept"`
+- **Unicode slug**：文章和笔记支持有意使用 Unicode slug，修改动态路由时要一起验证 ASCII 和 Unicode 路径
 
 ## 项目结构
 
@@ -152,11 +199,17 @@ amytis/
     books/
     notes/
     flows/
+  docs/
+  imports/
   public/
+  scripts/
   src/
     app/
     components/
     lib/
+  tests/
+  packages/
+    create-amytis/
   site.config.ts
 ```
 

package/TODO.md

@@ -1,18 +1,19 @@
 # Amytis Roadmap
 
 ## 🚀 Priority UX & Engineering
-- [ ] **Image Zoom**: Implement medium-zoom or a lightbox for MDX images.
 - [ ] **Breadcrumbs**: Extend Flow breadcrumbs to standard Posts and Books.
 - [ ] **Dynamic OG**: Generate automated social cards with Satori for every post.
 - [ ] **PWA Support**: Add manifest and service worker for offline reading.
-- [ ] **SEO Boost**: Implement JSON-LD structured data for Articles, Books, and Breadcrumbs.
+- [ ] **Image Zoom**: Implement medium-zoom or a lightbox for MDX images.
 
 ## 🌿 Digital Garden Evolution
-- [ ] **Knowledge Graph**: 
+- [ ] **Knowledge Graph**:
   - [ ] Interactive fullscreen mode for the graph.
   - [ ] Filter graph by tags or content types.
   - [ ] "Local Graph" view in the sidebar of individual notes.
-- [ ] **Discovery**: 
+- [ ] **Hover Preview**: Show a floating excerpt card when hovering over wiki-links, without navigating away.
+- [ ] **Transclusion**: Embed another note or post's content inline using `![[slug]]` syntax.
+- [ ] **Discovery**:
   - [ ] "On this day" section for Flows (history from previous years).
   - [ ] RSS/Atom feeds for specific categories or tags.
 - [ ] **Notes**: Support for un-linked mentions (searching for note titles in plain text).
@@ -23,6 +24,7 @@
 - [ ] **Optimization**: Automatically compress and resize co-located images during build.
 
 ## ✅ Completed Highlights
+- [x] **JSON-LD Structured Data**: `BlogPosting`, `Book`, and `Article` schemas for Google rich results.
 - [x] **Digital Garden**: Notes, Wiki-links, Backlinks, and interactive Knowledge Graph.
 - [x] **Pagefind Search**: High-performance static full-text indexing with rich UI.
 - [x] **Smart Navigation**: Persistent "Previous" and "Next" article links on all posts.