@hutusi/amytis 1.12.0 → 1.14.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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.14.0] - 2026-04-05
+
+### Added
+- **Type-Specific Feeds**: Introduced dedicated RSS and Atom feed endpoints for `/posts/feed.xml`, `/flows/feed.xml`, and a global `/all.xml` firehose, allowing readers to subscribe to specific content streams.
+- **Namespaced Collections**: Collection items now support `folder/slug` syntax (e.g., `posts/my-post`, `web-dev/intro`) for explicit resolution, preventing slug collisions across different content directories.
+- **Enhanced Feed Metadata**: Added RFC 4287 compliant author fallbacks for Atom feeds and optimized feed generation with lazy HTML rendering.
+
+### Changed
+- **Copy-Paste UX**: Wrapped article content in background-stable containers to prevent "striping" when pasting into rich-text editors and applied `select-none` to navigation and sidebars for cleaner content selection.
+- **Archive Page Robustness**: Refactored the chronological archive layout to prioritize titles and gracefully truncate long author lists, preventing layout shifts on posts with many contributors.
+- **Test Coverage**: Added comprehensive integration tests for namespaced resolution and E2E tests for the new feed architecture.
+
+### Fixed
+- **XML Template Literals**: Fixed a syntax issue with escaped backticks in the RSS/Atom generator that caused build-time errors.
+- **Archive Mobile Layout**: Improved layout stability on mobile devices for archive timeline entries.
+
+## [1.13.0] - 2026-03-25
+
+### Added
+- **Slug Rename Redirects**: Added `redirectFrom` support for post slug renames within the same URL prefix so renamed content can keep resolving from legacy paths.
+- **Series Slug Migration**: Added `redirectFrom` support for series slug renames, preserving access to older series URLs after route changes.
+
+### Changed
+- **Series Routing Defaults**: `series.autoPaths` now defaults to `true`, making `/<series-slug>/<post-slug>` the standard route shape for series posts.
+- **README Positioning**: Updated the English README to match the latest Chinese version, including the project backstory and refreshed documentation structure.
+
+### Fixed
+- **Route Conflict Handling**: Prevented auto-path series slugs from colliding with configured `series.customPaths` values during route generation.
+
 ## [1.12.0] - 2026-03-08
 
 ### Added

package/GEMINI.md

@@ -40,15 +40,18 @@ bun test
   - `flows/`: Stream-style daily notes or micro-blogging (`[year]/[month]/[day]`).
   - `series/`: Series overview and individual series catalog pages with pagination support.
   - `books/`: Books overview and individual book/chapter pages (`[slug]/[chapter]`).
+  - `notes/`: Evergreen notes index and individual note pages with backlinks.
   - `archive/`: Timeline-based chronological archive grouped by year and month.
   - `tags/`: Popularity-sorted tag cloud and filtered listings.
   - `authors/`: Posts filtered by individual authors.
+  - `graph/`: Interactive knowledge graph visualization of all connected content.
   - `subscribe/`: Subscription options (RSS, Newsletter, Social).
   - `search.json/`: Static search index generator (supplementary).
 - `src/lib/`: Core logic and utilities.
   - `markdown.ts`: Advanced parsing for posts/series/flows, sorting, and metadata.
   - `search-utils.ts`: Content cleaning and search result processing.
   - `shuffle.ts`: Deterministic and random array shuffling.
+  - `urls.ts`: Centralized URL routing and link generation logic.
 - `src/components/`: Modular UI blocks (Hero, HorizontalScroll, Search, CoverImage, ShareBar, etc.).
 - `content/`: Source Markdown/MDX content.
 - `scripts/`: CLI tools for content management and asset processing.
@@ -57,10 +60,12 @@ bun test
 
 ### Advanced Content Management
 - **Posts**: Supports both flat files (`.mdx`) and nested folders (`/index.mdx`) with co-located assets.
-- **Flows**: Daily notes or micro-posts organized by date (`YYYY/MM/DD`). Designed for quick thoughts and stream-of-consciousness updates.
+- **Flows**: Daily notes or micro-posts organized by date (`YYYY/MM/DD`). Designed for quick thoughts and stream-of-consciousness updates. Supports optional titles via frontmatter or H1 headings.
 - **Series**: 
   - Robust grouping with folder-based or file-based entries.
   - Configurable sorting: `date-asc`, `date-desc`, or `manual` (explicit list of slugs).
+  - **Collections**: Specialized series (`type: collection`) that allow manual curation of posts and other series.
+  - **Namespaced Referencing**: Collection items support `folder/slug` syntax (e.g., `posts/my-post`, `web-dev/intro`) to explicitly resolve posts and prevent collisions across different content directories.
   - Cross-referencing: Series can include posts from the general pool or other folders.
   - Metadata inheritance: Posts can inherit attributes (like authors) from series index files.
 - **Featured Content**: Mark posts or series as `featured` to display them in prominent homepage sections with horizontal scrolling.
@@ -95,3 +100,6 @@ bun test
 - Added pagination to the main posts list and individual series pages.
 - Implemented sophisticated reading time calculation for mixed Latin and CJK text.
 - Enhanced author management with metadata inheritance and slug-based routing.
+- Implemented **Namespaced Collections**: manually curated series now support `folder/slug` references to prevent post collisions and ensure explicit content resolution.
+- Added **Type-Specific Feeds**: dedicated RSS/Atom endpoints for `/posts`, `/flows`, and a global `/all` firehose.
+- Improved **Copy-Paste UX**: wrapped article content in background-stable containers and added `select-none` to UI navigation to ensure clean, high-fidelity content selection.

package/README.md

@@ -2,22 +2,37 @@
 
 [English](README.md) | [简体中文](README.zh.md)
 
-**Amytis** is an elegant, open-source framework for building a personal digital garden: a living knowledge space where ideas grow from raw notes to refined writing. It is built with Next.js 16, React 19, and Tailwind CSS v4, with a strong focus on readability, structure, and long-term content ownership.
+**Amytis** is a powerful, elegant, and user-friendly open-source digital garden framework for building knowledge spaces, blogs, showcase sites, or internal knowledge bases. It is built with Next.js 16, Tailwind CSS v4, and Bun, emphasizing a Markdown-first, plain-text-first workflow that preserves long-term content ownership while pursuing simplicity, elegance, and performance.
 
 [**Live Demo**](https://amytis.vercel.app/)
 
 ![Amytis Screenshot](public/images/amytis-screenshot.jpg)
 
-## The Knowledge Ladder
+## Why Amytis?
 
-Amytis is built around a simple path from rough to refined:
+I have been [blogging for twenty years](https://hutusi.com/archive), starting from early blogging platforms such as MSN Space (MS Live Space) and Sina Blog, then moving to self-hosted WordPress and Drupal, and later fully adopting static blogging frameworks after GitHub Pages became available. I tried Jekyll, Hugo, and several of their themes, but none of them truly satisfied me. The feature-rich ones were often not simple or elegant enough, while the elegant ones usually lacked flexibility and customization. I kept wondering whether a blogging or knowledge platform framework could balance functionality, performance, aesthetics, and UX. That idea stayed with me for years. When I finally decided to build one myself, I found it much harder than I had expected.
 
-- **Flow**: Capture raw daily thoughts and fragments.
-- **Articles**: Refine one idea into a clear essay.
-- **Series**: Connect related articles into a curated narrative.
-- **Books**: Distill mature knowledge into structured chapters and parts.
+Fortunately, AI coding changed that equation. With the help of Claude Code, Gemini CLI, and Codex, it became much easier than before to turn the idea into reality. After more than 700 commits of iteration, Amytis finally took shape as the idealized knowledge platform framework I had been aiming for. It was first used in the geek community platform I built at work, and I also replaced the framework behind my Hutusi blog with it. Amytis is now open source. Independent bloggers and knowledge managers are welcome to use it, and contributions, bug reports, and pull requests are all appreciated. If you are using Amytis, feel free to leave a note in [this issue](https://github.com/hutusi/amytis/issues/49).
 
-Each stage builds on the previous one, so your garden can evolve naturally.
+### The Knowledge Ladder
+
+Amytis is built around a path from fragmented thoughts to refined knowledge, helping individuals or teams build a complete digital garden system:
+
+- **Flow**: Capture daily thoughts and brainstorming fragments.
+- **Articles**: Refine a single idea into a clear article.
+- **Series**: Connect related articles into a thematic narrative.
+- **Books**: Distill mature knowledge into structured, chapter-based books.
+
+Each stage builds on the one before it, so the garden can grow naturally.
+
+### Design Philosophy
+
+- **Elegance by default**: Typography, spacing, and color should feel polished out of the box and remain visually consistent.
+- **Content and plain text first**: Writing and publishing should happen through file-based workflows rather than a heavyweight CMS. Content lives in Markdown/MDX, can be versioned with Git, and remains portable over time.
+- **Markdown-first, not markdown-limited**: Markdown and common extensions are supported by default, while math, diagrams, code, and bidirectional links remain first-class.
+- **Ship what you need**: `site.config.ts` provides modular switches so you only enable the capabilities you actually need.
+
+Further reading: [How to Get AI to Write Better Code](https://hutusi.com/weeklies/25) (Chinese)
 
 ## Features
 
@@ -43,6 +58,7 @@ Each stage builds on the previous one, so your garden can evolve naturally.
   - Light/Dark mode with automatic system detection.
   - Four color palettes: default (emerald), blue, rose, amber.
   - Responsive layout optimized for reading.
+  - Clean Selection: UI elements are non-selectable to ensure high-fidelity copy-pasting of article content.
   - Horizontal scrolling for featured content on the homepage.
 - **Table of Contents:** Sticky TOC with scroll tracking, reading progress indicator, and active heading highlight.
 - **Flexible Content Structure:**
@@ -55,7 +71,7 @@ Each stage builds on the previous one, so your garden can evolve naturally.
   - Fully static export with optimized WebP images.
   - 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`).
+  - RSS/Atom feeds including a main curated feed (`feed.xml`), plus type-specific feeds (`/posts/feed.xml`, `/flows/feed.xml`, `/all.xml`). 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:**
@@ -65,14 +81,6 @@ Each stage builds on the previous one, so your garden can evolve naturally.
 - **Content CLI Tools:** Create posts, series, and import from PDFs or image folders.
 - **Modern Stack:** Next.js 16, React 19, Tailwind CSS v4, TypeScript 5, Bun.
 
-## Design Philosophy
-
-- **Elegance by default**: Typography, spacing, and color should feel intentional out of the box.
-- **Content over configuration**: Writing and publishing should be simple file-based workflows, not CMS-heavy setup.
-- **Markdown-first, not markdown-limited**: Keep authoring portable while supporting rich output (math, diagrams, code, wikilinks).
-- **Ship what you need**: Features are modular through `site.config.ts`; disable sections you do not use.
-- **Plain text, long-term ownership**: Content stays in Markdown/MDX so it remains versionable and portable.
-
 ## Quick Start
 
 ### New Project (Recommended)
@@ -224,6 +232,7 @@ 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`
+- Optional Title: Set `title` in frontmatter or use an `# Heading` in the content to display a title alongside the date.
 
 ### Series
 

package/README.zh.md

@@ -2,73 +2,90 @@
 
 [English](README.md) | [简体中文](README.zh.md)
 
-**Amytis** 是一个优雅的开源数字花园框架，用于构建个人知识空间。它基于 Next.js 16、React 19 和 Tailwind CSS v4，强调可读性、结构化表达与长期内容所有权。
+**Amytis** 是一个功能强大、设计优雅、交互友好的开源数字花园框架，用于构建知识空间、博客、展示页面或企业知识库等。它基于 Next.js 16、Tailwind CSS v4 和 Bun 构建，强调 Markdown 优先、文本优先，保障作者对内容的长期所有权，在不损失功能和性能的前提下追求极致简洁与优雅。
 
 [**在线演示**](https://amytis.vercel.app/)
 
 ![Amytis 截图](public/images/amytis-screenshot.jpg)
 
-## 知识阶梯
+## 为什么要做 Amytis ?
 
-Amytis 围绕一条从粗糙到精炼的知识路径构建：
+我写[博客有二十年](https://hutusi.com/archive)了，从最早的博客平台，如 MSN Space (MS Live Space)、新浪博客，到自己搭建 Wordpress、Drupal, 再到 GitHub Pages 推出后全面采用静态博客框架，折腾过 Jekyll、Hugo 及其多个主题，但没有一个框架或主题能让自己真正满意。功能复杂的不够简洁或优雅，简洁优雅的又缺少功能定制。能不能有一款兼顾功能、性能、美观、UX 的博客或知识平台框架呢？这个想法最近几年一直萦绕在我的脑海，实在找不到那就做一个，等到准备付诸实践，才发现难度比想象中的要大得多。
 
-- **Flow（随笔）**：记录每日想法与碎片。
-- **Articles（文章）**：将单个想法打磨成清晰文章。
+好在有 AI 编程，在 Claude Code/Gemini CLI/Codex 的帮助下，比以往要更容易实现自己的想法，在经过 700 多次 Commit 的打磨后，理想化的知识平台框架 —— Amytis 终于交付成稿，我在公司搭建的极客社区平台首次应用，并将胡涂说博客网站框架也进行了替换。同时，也将 Amytis 开源，欢迎更多的独立博主/知识管理者使用，更欢迎帮忙发现问题、提 PR 添砖加瓦。如果你也在使用 Amytis, 欢迎在[此 issue 留言](https://github.com/hutusi/amytis/issues/49)。
+
+### 知识阶梯
+
+Amytis 围绕一条从碎片想法到精炼知识的路径来帮助个人或组织构建完整的数字花园体系：
+
+- **Flow（心流）**：记录每日想法与头脑风暴的灵感碎片。
+- **Articles（文章）**：将单个想法打磨成清晰的文章。
 - **Series（系列）**：把相关文章串联为一条主题叙事。
-- **Books（书籍）**：将成熟知识沉淀为章节化结构。
+- **Books（书籍）**：将成熟知识沉淀为章节化结构的书籍。
 
-每个阶段都建立在上一阶段之上，花园会自然生长。
+每个阶段都建立在上一阶段之上，数字花园会自然生长。
 
-## 功能特性
+### 设计理念
 
-- **数字花园体验**：通过标签、系列、作者、书籍、Flow 和归档进行非线性导航。
-- **互联知识网络**：
-  - **双向链接**：支持 `[[Slug]]` 跨内容类型关联。
-  - **反向链接**：在笔记页自动显示“Linked References”。
-  - **知识图谱**：以可视化方式展示内容连接关系。
-- **全文搜索**：基于 Pagefind 的静态搜索，支持 Cmd/Ctrl+K 快捷键。
-- **结构化内容体系**：
-  - **Series**：支持手动或自动排序的多篇集合。
-  - **Books**：支持章节与分部的长篇阅读界面。
-  - **Notes**：原子化常青笔记。
-  - **Flows**：流式日记/微记录。
-- **富文本 MDX 能力**：
-  - GitHub Flavored Markdown（表格、任务列表等）
-  - 代码高亮
-  - Mermaid 图表
-  - KaTeX 数学公式
-  - 原生 HTML 支持
-- **阅读体验与设计**：
-  - 高可读排版与响应式布局
-  - 自动系统主题检测（明/暗）
-  - 四套配色主题：default、blue、rose、amber
-  - 吸顶目录与阅读进度跟踪
-- **作者生态**：每位作者有独立主页，包含简介、头像与社交链接。文章支持按作者筛选，并可在文末显示作者卡片。
-- **性能与 SEO**：
-  - 全静态导出与 WebP 优化
-  - 每种内容类型均有完整的 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
-  - 评论：Giscus / Disqus
-  - i18n：`site.config.ts` 中配置多语言（en / zh）
-
-## 设计理念
-
-- **默认优雅**：排版、间距、色彩开箱即用且有审美一致性。
-- **内容优先**：通过文件化写作与发布流程完成创作，不依赖重型 CMS。
-- **Markdown 优先但不受限**：保持可迁移写作体验，同时支持数学、图表、代码和双向链接。
+- **简洁优雅**：排版、间距、配色开箱即用，且遵循审美一致性。
+- **内容及文本优先**：通过文本文件化写作与发布流程完成创作，不依赖重型 CMS，内容存储于 Markdown/MDX 文本，结合 Git 进行版本管理，使作者拥有长期所有权并便于平台迁移。
+- **Markdown 优先**：默认支持 Markdown 及常用扩展语法，同时支持数学、图表、代码和双向链接。
 - **按需启用**：`site.config.ts` 提供模块化开关，仅启用你需要的能力。
-- **纯文本长期所有权**：内容存储于 Markdown/MDX，便于版本管理与长期迁移。
+
+延伸阅读：[《如何让 AI 写好代码》](https://hutusi.com/weeklies/25)（中文）
+
+## 功能特性
+
+- **数字花园理念:** 通过标签、系列、作者、书籍、Flow 和时间归档实现非线性导航。
+- **互联知识网络:**
+  - **Wiki 链接:** 支持在所有内容类型之间使用 `[[Slug]]` 建立双向关联。
+  - **反向链接:** 在笔记页面自动展示 “Linked References”。
+  - **知识图谱:** 以交互式可视化方式展示内容之间的连接关系。
+- **全文搜索:** 基于 Pagefind 的快速静态客户端全文搜索，支持 Cmd/Ctrl+K。
+- **结构化内容体系:**
+  - **Series:** 支持手动或自动排序的多篇内容组织方式。
+  - **Books:** 支持明确章节、分部以及专用阅读界面的长篇内容。
+  - **Notes:** 面向个人知识管理的原子化常青概念。
+  - **Flows:** 用于快速记录想法的流式日记或微博客。
+- **丰富的 MDX 内容能力:**
+  - GitHub Flavored Markdown（表格、任务列表、删除线）。
+  - 语法高亮代码块。
+  - Mermaid 图表（流程图、时序图等）。
+  - 通过 KaTeX 支持 LaTeX 数学公式。
+  - 支持原生 HTML 以实现自定义布局。
+- **优雅设计:**
+  - 极简审美与高对比度排版。
+  - 明暗主题，自动跟随系统设置。
+  - 四套配色方案: default（emerald）、blue、rose、amber。
+  - 针对阅读优化的响应式布局。
+  - 纯净选区: UI 元素不可选中，确保文章内容的高保全复制。
+  - 首页精选内容支持横向滚动。
+- **目录:** 吸顶目录支持滚动跟踪、阅读进度指示和当前标题高亮。
+- **灵活的内容结构:**
+  - 支持平铺文件（`post.mdx`）或嵌套文件夹（`post/index.mdx`）。
+  - 资源可与文章共置: 将图片保存在文章目录内（`./images/`）。
+  - 支持带日期前缀的文件名: `2026-01-01-my-post.mdx`。
+  - 支持文章、系列、书籍和 Flows 的草稿状态。
+- **作者生态:** 每位作者都有独立主页，包含简介、头像和社交链接。文章可按作者筛选，文末可选显示作者卡片。
+- **性能与 SEO:**
+  - 全静态导出，并生成优化后的 WebP 图片。
+  - 为所有内容类型生成 Open Graph 和 Twitter Card 元数据。
+  - 提供 JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体结果。
+  - RSS/Atom 订阅源包含一个主 curated 订阅 (`feed.xml`)，以及分类订阅（`/posts/feed.xml`, `/flows/feed.xml`, `/all.xml`）。支持可配置的格式（`rss` | `atom` | `both`）和内容深度（`full` | `excerpt`）。
+  - 在 `<head>` 中自动注入 Feed 自动发现链接，并原生生成 sitemap。
+  - 多语言阅读时长估算，支持 Latin 和 CJK。
+- **集成能力:**
+  - 分析统计: Umami、Plausible 或 Google Analytics。
+  - 评论系统: Giscus（GitHub Discussions）或 Disqus。
+  - 国际化: 通过本地化的 `site.config.ts` 支持多语言（en、zh）。
+- **内容 CLI 工具:** 支持创建文章、系列，以及从 PDF 或图片文件夹导入内容。
+- **现代技术栈:** Next.js 16、React 19、Tailwind CSS v4、TypeScript 5、Bun。
 
 ## 快速开始
 
 ### 新建项目（推荐）
 
-一条命令创建新的 Amytis 站点：
+用一条命令创建新的 Amytis 站点:
 
 ```bash
 bun create amytis my-garden
@@ -76,30 +93,36 @@ cd my-garden
 bun dev
 ```
 
-该脚手架会下载最新发布版 Amytis，自动安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
+脚手架命令会下载最新打标签发布的 Amytis 版本，安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
 
-### 克隆运行
+### 克隆并运行
+
+1. **安装依赖:**
 
-1. **安装依赖**
    ```bash
    bun install
    ```
 
-2. **启动开发环境**
+2. **启动开发服务器:**
+
    ```bash
    bun dev
    ```
-   打开 [http://localhost:3000](http://localhost:3000)。
 
-   > **本地搜索说明：** Pagefind 索引是在执行 `bun run build:dev` 时生成的。本地测试 Cmd/Ctrl+K 前先运行一次；内容更新后也需要重新生成。
+   访问 [http://localhost:3000](http://localhost:3000)。
+
+   > **开发环境中的搜索:** Pagefind 索引会在执行 `bun run build:dev` 时生成。本地测试 Cmd/Ctrl+K 前请先运行一次；内容更新后也需要重新生成。
+
+3. **生产构建（静态导出）:**
 
-3. **生产构建（静态导出）**
    ```bash
    bun run build
    ```
-   产物位于 `out/` 目录。
 
-4. **开发构建（更快，无图片优化）**
+   静态站点会生成到 `out/` 目录，并包含优化后的图片资源。
+
+4. **开发构建（更快，无图片优化）:**
+
    ```bash
    bun run build:dev
    ```
@@ -117,7 +140,7 @@ bun run validate
 bun run build
 bun run build:dev
 bun run clean
-bun run deploy                 # 部署到 Linux/nginx 服务器（需要 .env.local 配置）
+bun run deploy                 # 部署到 Linux/nginx 服务器（需要 .env.local）
 
 ## Test
 bun test
@@ -144,81 +167,138 @@ bun run series-draft "series-slug"
 bun run add-series-redirects --dry-run
 ```
 
-### 导入聊天记录到 Flows
+### 将聊天记录导入为 Flows
 
-将 `.txt` 或 `.log` 文件放入 `imports/chats/` 后执行：
+将 `.txt` 或 `.log` 文件放入 `imports/chats/`，然后执行:
 
 ```bash
 bun run new-flow-from-chat
 ```
 
-常用参数：`--all`、`--dry-run`、`--author "Name"`、`--append`、`--timestamp`。  
-导入历史记录位于 `imports/chats/.imported`。
+常用参数: `--all`、`--dry-run`、`--author "Name"`、`--append`、`--timestamp`。  
+导入历史会记录在 `imports/chats/.imported` 中。
 
 ## 配置
 
-主要站点配置集中在 `site.config.ts`，`site.config.example.ts` 则是更完整的参考模板，适合查看可选项和默认写法。
+主要站点配置位于 `site.config.ts`。`site.config.example.ts` 是脚手架所使用的参考模板，查看新选项时很有用:
+
+```typescript
+export const siteConfig = {
+  // ...
+  nav: [
+    { name: "Home", url: "/", weight: 1 },
+    { name: "Flow", url: "/flows", weight: 1.1 }, // 在导航中添加 Flows
+    { name: "Series", url: "/series", weight: 1.5 },
+    { name: "Books", url: "/books", weight: 1.7 },
+    { name: "Archive", url: "/archive", weight: 2 },
+    // ...
+  ],
+  // ...
+  flows: {
+    recentCount: 5,
+  },
+};
+```
 
-优先关注这些配置区块：
+优先自定义这些高影响配置区块:
 
-- 站点信息：`title`、`description`、`baseUrl`、`ogImage`、`logo`
-- 导航与页脚：`nav`、`footer`、`subscribe`、`social`
-- 内容路由：`posts.basePath`、`posts.includeDateInUrl`、`series.autoPaths`、`series.customPaths`
-- 首页结构：`hero`、`homepage.sections`
-- 集成能力：`analytics`、`comments`、`feed`、`i18n`
+- 站点标识: `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` 开始调整。
+如果是通过 nginx 进行静态托管，可以从 `nginx.conf.example` 开始配置。
 
 ## 静态导出路由规则
 
-Amytis 基于 Next.js 静态导出，核心约束是 `output: "export"` 和 `trailingSlash: true`。
+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`
+- 在 `generateStaticParams()` 中返回原始 segment 值，不要预先用 `encodeURIComponent` 编码。
+- 链接应指向真实 URL，例如 `/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/`，支持单文件、日期前缀和文件夹模式。文件夹模式可将图片放在同目录的 `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 路径
+### Posts
+
+在 `content/posts/` 中创建 `.md` 或 `.mdx` 文件。
+
+- 平铺文件: `content/posts/my-post.mdx`
+- 日期前缀文件: `content/posts/2026-01-01-my-post.mdx`
+- 带共置资源的文件夹文章: `content/posts/my-post/index.mdx`，并配合 `content/posts/my-post/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` 会创建今天的记录
+- 聊天导入: 将导出文件放入 `imports/chats/`，然后运行 `bun run new-flow-from-chat`
+- 可选标题: 在 frontmatter 中设置 `title` 或在内容中使用 `# 标题`，即可在日期旁显示标题。
+
+### Series
+
+在 `content/series/<slug>/` 下创建目录和 `index.mdx`，然后将系列文章作为同级文件或文件夹加入其中。
+
+- CLI: `bun run new-series "Series Name"`
+- 也可以直接将文章创建到已有系列中: `bun run new "Post Title" --series <series-slug>`
+
+### Books
+
+书籍是位于 `content/books/<slug>/` 下的长篇结构化内容。
+
+- 使用 `index.mdx` 保存书籍元数据
+- 在同目录添加章节文件，例如 `introduction.mdx` 或 `setup.mdx`
+- 与书籍相关的工作流可使用 `bun run import-book` 和 `bun run sync-book`
+
+### Notes
+
+在 `content/notes/` 中创建常青笔记（例如 `concept.mdx`），并使用 `[[wiki-links]]` 将它们连接起来。
+
+- CLI: `bun run new-note "Concept"`
+- 在需要时，Notes 和 Posts 都支持有意使用 Unicode slug
 
 ## 项目结构
 
 ```text
 amytis/
   content/
-    posts/
-    series/
-    books/
-    notes/
-    flows/
-  docs/
-  imports/
-  public/
-  scripts/
+    posts/              # 博客文章
+    series/             # 系列集合
+    books/              # 长篇书籍
+    notes/              # 数字花园笔记
+    flows/              # 日记内容（YYYY/MM/DD）
+    about.mdx           # 静态页面
+  docs/                 # 架构、部署、排障文档
+  imports/              # 仅本地使用的导入源文件
+  public/               # 静态资源
+  scripts/              # Bun 编写/构建/导入工具
   src/
-    app/
-    components/
+    app/                # Next.js App Router 页面
+      books/            # 书籍路由
+      notes/            # 笔记路由
+      graph/            # 知识图谱
+      flows/            # Flow 路由
+    components/         # React 组件
     lib/
-  tests/
+      markdown.ts       # 数据访问层
+  tests/                # 单元、集成、e2e、工具测试
   packages/
-    create-amytis/
-  site.config.ts
+    create-amytis/      # `bun create amytis` 脚手架 CLI
+  site.config.ts        # 站点配置
 ```
 
 ## 文档
 
-- [架构说明](docs/ARCHITECTURE.md)
+- [架构总览](docs/ARCHITECTURE.md)
 - [部署指南](docs/deployment.md)
 - [数字花园指南](docs/DIGITAL_GARDEN.md)
 - [贡献指南](docs/CONTRIBUTING.md)
+- [故障排查](docs/TROUBLESHOOTING.md)
 
 ## 许可证