@hutusi/amytis 1.13.0 → 1.15.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,38 @@ 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.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
+- **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

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

@@ -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.
@@ -58,6 +60,7 @@ Further reading: [How to Get AI to Write Better Code](https://hutusi.com/weeklie
   - 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:**
@@ -70,7 +73,7 @@ Further reading: [How to Get AI to Write Better Code](https://hutusi.com/weeklie
   - 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:**
@@ -212,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
@@ -231,14 +236,43 @@ 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
 
-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:** 用于快速记录想法的流式日记或微博客。
@@ -58,6 +60,7 @@ Amytis 围绕一条从碎片想法到精炼知识的路径来帮助个人或组
   - 明暗主题，自动跟随系统设置。
   - 四套配色方案: default（emerald）、blue、rose、amber。
   - 针对阅读优化的响应式布局。
+  - 纯净选区: UI 元素不可选中，确保文章内容的高保全复制。
   - 首页精选内容支持横向滚动。
 - **目录:** 吸顶目录支持滚动跟踪、阅读进度指示和当前标题高亮。
 - **灵活的内容结构:**
@@ -70,7 +73,7 @@ Amytis 围绕一条从碎片想法到精炼知识的路径来帮助个人或组
   - 全静态导出，并生成优化后的 WebP 图片。
   - 为所有内容类型生成 Open Graph 和 Twitter Card 元数据。
   - 提供 JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体结果。
-  - RSS/Atom 订阅源支持可配置的格式（`rss` | `atom` | `both`）和内容深度（`full` | `excerpt`）。
+  - RSS/Atom 订阅源包含一个主 curated 订阅 (`feed.xml`)，以及分类订阅（`/posts/feed.xml`, `/flows/feed.xml`, `/all.xml`）。支持可配置的格式（`rss` | `atom` | `both`）和内容深度（`full` | `excerpt`）。
   - 在 `<head>` 中自动注入 Feed 自动发现链接，并原生生成 sitemap。
   - 多语言阅读时长估算，支持 Latin 和 CJK。
 - **集成能力:**
@@ -218,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`，以确保旧链接仍然可访问。
 
 ## 内容写作
@@ -237,14 +242,43 @@ Amytis 基于 Next.js 静态导出构建，关键配置为 `output: "export"`
 
 - CLI: `bun run new-flow` 会创建今天的记录
 - 聊天导入: 将导出文件放入 `imports/chats/`，然后运行 `bun run new-flow-from-chat`
+- 可选标题: 在 frontmatter 中设置 `title` 或在内容中使用 `# 标题`，即可在日期旁显示标题。
 
 ### 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.