@hutusi/amytis 1.11.0 → 1.13.0

package/AGENTS.md

@@ -6,8 +6,10 @@
 - `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.
@@ -18,8 +20,8 @@
 - `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.
-- 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-book`, `bun run sync-book`, `bun run series-draft`.
+- `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.
@@ -31,7 +33,8 @@
 - 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 may also resolve through custom top-level paths via `series.customPaths` and `[slug]/[postSlug]`; preserve those URL helpers instead of hardcoding paths.
+- 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

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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.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
+- **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

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
@@ -157,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

@@ -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
 
@@ -65,14 +80,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)
@@ -119,6 +126,7 @@ The scaffold command downloads the latest tagged Amytis release, installs depend
 ## Core
 bun dev
 bun run lint
+bun run build:graph
 bun run validate
 
 ## Build & Deploy
@@ -132,6 +140,7 @@ 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"
@@ -144,9 +153,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
@@ -162,7 +173,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 = {
@@ -182,27 +193,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
 
@@ -215,7 +265,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
@@ -225,6 +278,7 @@ 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
@@ -236,6 +290,7 @@ amytis/
 - [Deployment Guide](docs/deployment.md)
 - [Digital Garden Guide](docs/DIGITAL_GARDEN.md)
 - [Contributing Guide](docs/CONTRIBUTING.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
 
 ## License