@hutusi/amytis 1.5.6 → 1.7.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+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.6.0] - 2026-02-20
+
+### Added
+- **Search Engine Upgrade**: Migrated from Fuse.js to **Pagefind** for high-performance, static full-text search with extremely low client-side overhead.
+- **Enhanced Search UI**:
+  - Full-content search with context highlighting and excerpts.
+  - Type-based filtering tabs (All, Post, Flow, Book).
+  - Recent searches history persisted in local storage.
+  - Interactive search tips panel with syntax hints.
+  - Advanced keyboard navigation (Tab-based focus trap, arrow keys, Alt+number shortcuts).
+  - Debounced input and visual loading states.
+  - Full-screen responsive layout for mobile devices.
+- **Search Utilities**: New unit-tested utility library for processing search results and metadata.
+- **Project Documentation**: Added a comprehensive `CHANGELOG.md` documenting the project's evolution from 1.0.0.
+
+### Changed
+- **Documentation Overhaul**: Streamlined `TODO.md` roadmap and updated `GEMINI.md` and `ARCHITECTURE.md` to reflect the new search architecture.
+- **i18n**: Fully localized search interface supporting both English and Chinese.
+
+### Fixed
+- **Hydration**: Suppressed body-level hydration warnings caused by browser extensions.
+- **Search Precision**: Improved title cleaning and date extraction for search results.
+
+## [1.5.6] - 2026-02-19
+
+### Added
+- **Scoped Publishing**: Transitioned to `@hutusi/amytis` for official release on npm and GitHub.
+- **Trusted Publishing**: Implemented secure OIDC-based deployment for npm.
+- **Engineering Quality**: Added `bun run validate` to integrate linting, testing, and building.
+
+### Changed
+- **Refined DX**: Cleaned up all linting warnings and optimized interactive components with `requestAnimationFrame` cleanup.
+- **Better Accessibility**: Improved `MarkdownRenderer` semantics by preserving native `<p>` tags.
+
+### Fixed
+- **Hydration & Stability**: Resolved all React 19 hydration mismatches in `LanguageProvider`, `Hero`, and `ThemeToggle`.
+- **Content Fixes**: Corrected mangled LaTeX formulas and resolved duplicated frontmatter mapping keys.
+
+## [1.5.0] - 2026-02-18
+
+### Added
+- **Daily Notes (Flows)**: A new stream-style content format for micro-blogging and quick thoughts.
+- **Full-text Search**: Migrated to **Pagefind** for high-performance static full-text indexing.
+- **Metadata Inheritance**: Implemented logic for posts to inherit attributes from series metadata.
+
+### Changed
+- **Major Tech Upgrade**: Modernized architecture to **Next.js 16 (App Router)** and **React 19**.
+- **UI Overhaul**: Redesigned homepage with horizontal scroll featured sections and distinct card styles.
+- **Austere Elegance**: New design for Archive and Tags pages focusing on minimalism.
+
+## [1.4.0] - 2026-02-10
+
+### Added
+- **Books Feature**: Support for structured, multi-chapter long-form content.
+- **Reading Progress**: Integrated sticky progress bar and scroll tracking.
+- **Import Tooling**: New CLI commands for PDF and image folder ingestion.
+
+## [1.3.0] - 2026-02-05
+
+### Added
+- **Internationalization (i18n)**: Native support for English and Chinese with language switching.
+- **Smart Reading Time**: Multilingual character counting for accurate estimates.
+- **Author Pages**: Detailed statistics and contribution tracking.
+
+## [1.2.0] - 2026-01-30
+
+### Added
+- **Series Management**: Robust support for manual ordering and folder-based structures.
+- **Rich Code Blocks**: Syntax highlighting for 11+ languages with copy-to-clipboard.
+
+## [1.1.0] - 2026-01-20
+
+### Added
+- **Testing Suite**: Integrated Vitest/Bun Test with 64+ automated tests.
+- **Integrations**: Support for Giscus comments and multiple analytics providers (Umami/Plausible).
+
+## [1.0.0] - 2026-01-12
+
+### Added
+- **Initial Release**: Launch of **Amytis**, a high-performance digital garden and blog engine.
+- **Next.js Foundation**: Built on App Router for optimal static site generation (SSG).
+- **Advanced Markdown**: Native support for GFM, Mermaid diagrams, and LaTeX math.
+- **Refined Typography**: High-contrast typefaces and optimized readability.
+- **Theming System**: Four built-in palettes (`default`, `blue`, `rose`, `amber`) with Dark Mode.
+- **Content Organization**: Flexible flat-file and nested-folder post structures.
+- **Smart Discovery**: Client-side search, tag clouds, and chronological archives.
+- **SEO & Performance**: Automated Sitemap/RSS generation and optimized WebP delivery.

package/CLAUDE.md

@@ -22,7 +22,7 @@ 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)
+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
 
 # Content creation
@@ -58,6 +58,7 @@ bun run new-flow --mdx              # Use .mdx format instead
 
 - `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/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
@@ -187,7 +188,7 @@ chapters:
 - `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` - Client-side fuzzy search (Cmd/Ctrl+K) using Fuse.js
+- `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

package/GEMINI.md

@@ -1,14 +1,16 @@
 # Amytis Project Context
 
 ## Project Overview
-**Amytis** is a high-performance, elegant digital garden and blog engine built with **Next.js 16 (App Router)**, **React 19**, and **Tailwind CSS v4**. It is designed for cultivating thoughts and sharing knowledge with a focus on typography, readability, and flexible content organization.
+**Amytis** (@hutusi/amytis) is a high-performance, elegant digital garden and blog engine built with **Next.js 16 (App Router)**, **React 19**, and **Tailwind CSS v4**. It is designed for cultivating thoughts and sharing knowledge with a focus on typography, readability, and flexible content organization.
+
+The package is officially published to both **npm** and **GitHub Packages** with automated **Trusted Publishing** (OIDC).
 
 ### Main Technologies
 - **Framework**: Next.js 16 (App Router)
 - **Runtime/Package Manager**: [Bun](https://bun.sh/)
 - **Styling**: Tailwind CSS v4 with CSS-variable based themes and `@tailwindcss/typography`.
 - **Content**: Local MDX/Markdown files with Zod-validated frontmatter.
-- **Search**: Client-side fuzzy search using `Fuse.js`.
+- **Search**: Static full-text search using `Pagefind`.
 - **Diagrams**: Native support for `Mermaid` diagrams.
 - **Math**: LaTeX support via `rehype-katex`.
 
@@ -23,7 +25,7 @@ bun dev
 ```bash
 bun run build
 ```
-Generates a fully optimized static site in the `out/` directory.
+Generates a fully optimized static site in the `out/` directory with Pagefind search index.
 
 ### Linting & Testing
 ```bash
@@ -37,13 +39,17 @@ bun test
   - `posts/`: Paginated post listing and individual post routes.
   - `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]`).
   - `archive/`: Timeline-based chronological archive grouped by year and month.
   - `tags/`: Popularity-sorted tag cloud and filtered listings.
   - `authors/`: Posts filtered by individual authors.
-  - `search.json/`: Static search index generator.
+  - `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, reading time calculation (multilingual), and metadata inheritance.
-- `src/components/`: Modular UI blocks (Hero, HorizontalScroll, Search, CoverImage, etc.).
+  - `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.
+- `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.
 
@@ -70,6 +76,7 @@ bun test
 ### Build Pipeline
 - **Asset Mapping**: `scripts/copy-assets.ts` mirrors content assets to the public folder, handling relative path resolution for both flat and nested structures.
 - **Image Optimization**: Fully integrated with `next-image-export-optimizer` for optimized WebP delivery in static exports.
+- **Search Indexing**: `Pagefind` runs after build to generate a static search index from the output directory.
 
 ## Recent Updates
 - Added **Flows** feature: a stream for daily notes and micro-blogging.

package/README.md

@@ -9,7 +9,7 @@
 ## Features
 
 - **Digital Garden Philosophy:** Non-linear navigation through tags, series, authors, books, flows, and chronological archives.
-- **Fuzzy Search:** Instant, client-side search across all posts (Cmd/Ctrl+K) powered by Fuse.js.
+- **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.
   - **Books:** Long-form content with explicit chapters, parts, and a dedicated reading interface.

package/TODO.md

@@ -1,76 +1,21 @@
-# Future Roadmap
-
-## 🚀 High Priority (Next Steps)
-
-- [ ] **User Experience (UX)**
-  - [ ] **Code Blocks**: Add a "Copy to Clipboard" button.
-  - [ ] **Images**: Implement a Lightbox or Zoom-on-click feature.
-  - [ ] **Navigation**: Add Breadcrumbs (e.g., `Home > Category > Post`).
-  - [ ] **Navigation**: Add Previous/Next post links at the bottom of articles.
-
-## 🌿 Digital Garden Features
-
-- [ ] **Knowledge Graph**:
-  - [ ] **Backlinks**: Show "Pages that link here" at the bottom of posts.
-  - [ ] **Wiki-links**: Support `[[Internal Link]]` syntax.
-
-## 🔮 Future Enhancements
-
-- [ ] **Performance & App**
-  - [ ] **PWA**: Add `manifest.json` and service workers for offline support.
-  - [ ] **Search Optimization**: Optimize search index for large gardens (e.g. content segmentation).
-
-- [ ] **Visuals**
-  - [ ] **Dynamic OG Images**: Generate custom social cards with post title using `@vercel/og` (Satori).
-
-- [ ] **CLI Enhancements**
-  - [ ] **Interactive Mode**: Use prompts to select series, tags, and layouts when creating new posts.
-
-## ✅ Completed
-
-- [x] **Content Types**
-  - [x] **Flows**: Stream-style daily notes or micro-blogging.
-  - [x] **Books**: Structured long-form content with chapters.
-
-- [x] **Engagement**
-  - [x] **Comments**: Integrate Giscus (GitHub Discussions) for comments.
-
-- [x] **Engineering**
-  - [x] **Validation**: Add Zod schema validation for content frontmatter to prevent build errors.
-  - [x] **Testing**: Add E2E tests for the new search and navigation features.
-
-- [x] **SEO & Discovery**
-  - [x] Generate `sitemap.xml` for search engines.
-  - [x] Generate `rss.xml` / `atom.xml` for feed readers.
-  - [x] Add Open Graph (OG) meta tags for social sharing.
-
-- [x] **Navigation & UX**
-  - [x] Implement a client-side fuzzy Search bar (Command+K).
-  - [x] Add a sticky Table of Contents (TOC) with Unicode/Multilingual support.
-  - [x] Add "Reading Time" estimate to post headers.
-  - [x] Refine link styling (clean default, underline on hover).
-  - [x] **Hero Section**: Configurable, collapsible welcome mat.
-  - [x] **Themes**: Configurable color palettes (default, blue, rose, amber).
-  - [x] **i18n**: Client-side language switcher infrastructure.
-
-- [x] **Content & Architecture**
-  - [x] **Series**: Robust support for grouping related posts (file-based & folder-based).
-  - [x] **Series**: Manual sorting, cross-referencing, and configurable order.
-  - [x] **Related Posts**: Auto-suggest relevant articles.
-  - [x] **Cover Images**: Support local paths, external URLs, and generated text covers.
-  - [x] **Analytics**: Privacy-friendly configuration (Umami/Plausible/Google).
-
-- [x] **Performance**
-  - [x] Static Image Optimization (`next-image-export-optimizer`).
-  - [x] Automated image dimension injection.
-
-- [x] **CLI Tools**
-  - [x] `bun run new` script for scaffolding posts.
-  - [x] `bun run new-series` script for scaffolding series.
-
-- [x] **UI Polish & Refinements**
-  - [x] **Animations**: Define missing animation classes.
-  - [x] **Color Contrast**: Improve accessibility.
-  - [x] **Responsive Grids**: Improve mobile/tablet layouts.
-  - [x] **Archive Timeline**: Refine CSS.
-  - [x] **Loading States**: Add skeleton loaders.
+# 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.
+
+## 🌿 Digital Garden Evolution
+- [ ] **Backlinks**: Automatically list "Pages that link here" at the bottom of articles.
+- [ ] **Wiki-links**: Support `[[internal-link]]` syntax for easier cross-referencing.
+- [ ] **Knowledge Graph**: Interactive visual map of all connected notes.
+
+## ✅ Completed Highlights
+- [x] **Pagefind Search**: High-performance static full-text indexing with rich UI.
+- [x] **Smart Navigation**: Persistent "Previous" and "Next" article links on all posts.
+- [x] **Multi-format Content**: Native support for **Posts**, **Series**, **Books**, and **Flows**.
+- [x] **Professional Publishing**: Scoped `@hutusi/amytis` package with OIDC Trusted Publishing.
+- [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.

package/bun.lock

@@ -7,7 +7,6 @@
       "dependencies": {
         "@giscus/react": "^3.1.0",
         "@tailwindcss/typography": "^0.5.19",
-        "fuse.js": "^7.1.0",
         "github-slugger": "^2.0.0",
         "gray-matter": "^4.0.3",
         "image-size": "^2.0.2",
@@ -17,6 +16,7 @@
         "next-themes": "^0.4.6",
         "react": "19.2.4",
         "react-dom": "19.2.4",
+        "react-icons": "^5.5.0",
         "react-markdown": "^10.1.0",
         "react-syntax-highlighter": "^16.1.0",
         "rehype-katex": "^7.0.1",
@@ -38,6 +38,7 @@
         "babel-plugin-react-compiler": "1.0.0",
         "eslint": "^9.0.0",
         "eslint-config-next": "16.1.6",
+        "pagefind": "^1.4.0",
         "pdf-to-img": "^5.0.0",
         "tailwindcss": "^4.1.18",
         "typescript": "^5.9.3",
@@ -257,6 +258,18 @@
 
     "@nolyfill/is-core-module": ["@nolyfill/is-core-module@1.0.39", "", {}, "sha512-nn5ozdjYQpUCZlWGuxcJY/KpxkWQs4DcbMCmKojjyrYDEAGy4Ce19NN4v5MduafTwJlbKc99UA8YhSVqq9yPZA=="],
 
+    "@pagefind/darwin-arm64": ["@pagefind/darwin-arm64@1.4.0", "", { "os": "darwin", "cpu": "arm64" }, "sha512-2vMqkbv3lbx1Awea90gTaBsvpzgRs7MuSgKDxW0m9oV1GPZCZbZBJg/qL83GIUEN2BFlY46dtUZi54pwH+/pTQ=="],
+
+    "@pagefind/darwin-x64": ["@pagefind/darwin-x64@1.4.0", "", { "os": "darwin", "cpu": "x64" }, "sha512-e7JPIS6L9/cJfow+/IAqknsGqEPjJnVXGjpGm25bnq+NPdoD3c/7fAwr1OXkG4Ocjx6ZGSCijXEV4ryMcH2E3A=="],
+
+    "@pagefind/freebsd-x64": ["@pagefind/freebsd-x64@1.4.0", "", { "os": "freebsd", "cpu": "x64" }, "sha512-WcJVypXSZ+9HpiqZjFXMUobfFfZZ6NzIYtkhQ9eOhZrQpeY5uQFqNWLCk7w9RkMUwBv1HAMDW3YJQl/8OqsV0Q=="],
+
+    "@pagefind/linux-arm64": ["@pagefind/linux-arm64@1.4.0", "", { "os": "linux", "cpu": "arm64" }, "sha512-PIt8dkqt4W06KGmQjONw7EZbhDF+uXI7i0XtRLN1vjCUxM9vGPdtJc2mUyVPevjomrGz5M86M8bqTr6cgDp1Uw=="],
+
+    "@pagefind/linux-x64": ["@pagefind/linux-x64@1.4.0", "", { "os": "linux", "cpu": "x64" }, "sha512-z4oddcWwQ0UHrTHR8psLnVlz6USGJ/eOlDPTDYZ4cI8TK8PgwRUPQZp9D2iJPNIPcS6Qx/E4TebjuGJOyK8Mmg=="],
+
+    "@pagefind/windows-x64": ["@pagefind/windows-x64@1.4.0", "", { "os": "win32", "cpu": "x64" }, "sha512-NkT+YAdgS2FPCn8mIA9bQhiBs+xmniMGq1LFPDhcFn0+2yIUEiIG06t7bsZlhdjknEQRTSdT7YitP6fC5qwP0g=="],
+
     "@rtsao/scc": ["@rtsao/scc@1.1.0", "", {}, "sha512-zt6OdqaDoOnJ1ZYsCYGt9YmWzDXl4vQdKTyJev62gFhRGKdx7mcT54V9KIjg+d2wi9EXsPvAPKe7i7WjfVWB8g=="],
 
     "@swc/helpers": ["@swc/helpers@0.5.15", "", { "dependencies": { "tslib": "^2.8.0" } }, "sha512-JQ5TuMi45Owi4/BIMAJBoSQoOJu12oOk/gADqlcUL9JEdHB8vyjUSsxqeNXnmXHjYKMi2WcYtezGEEhqUI/E2g=="],
@@ -767,8 +780,6 @@
 
     "functions-have-names": ["functions-have-names@1.2.3", "", {}, "sha512-xckBUXyTIqT97tq2x2AMb+g163b5JFysYk0x4qxNFwbfQkmNZoiRHb6sPzI9/QV33WeuvVYBUIiD4NzNIyqaRQ=="],
 
-    "fuse.js": ["fuse.js@7.1.0", "", {}, "sha512-trLf4SzuuUxfusZADLINj+dE8clK1frKdmqiJNb1Es75fmI5oY6X2mxLVUciLLjxqw/xr72Dhy+lER6dGd02FQ=="],
-
     "generator-function": ["generator-function@2.0.1", "", {}, "sha512-SFdFmIJi+ybC0vjlHN0ZGVGHc3lgE0DxPAT0djjVg+kjOnSqclqmj0KQ7ykTOLP6YxoqOvuAODGdcHJn+43q3g=="],
 
     "gensync": ["gensync@1.0.0-beta.2", "", {}, "sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg=="],
@@ -1173,6 +1184,8 @@
 
     "package-manager-detector": ["package-manager-detector@1.6.0", "", {}, "sha512-61A5ThoTiDG/C8s8UMZwSorAGwMJ0ERVGj2OjoW5pAalsNOg15+iQiPzrLJ4jhZ1HJzmC2PIHT2oEiH3R5fzNA=="],
 
+    "pagefind": ["pagefind@1.4.0", "", { "optionalDependencies": { "@pagefind/darwin-arm64": "1.4.0", "@pagefind/darwin-x64": "1.4.0", "@pagefind/freebsd-x64": "1.4.0", "@pagefind/linux-arm64": "1.4.0", "@pagefind/linux-x64": "1.4.0", "@pagefind/windows-x64": "1.4.0" }, "bin": { "pagefind": "lib/runner/bin.cjs" } }, "sha512-z2kY1mQlL4J8q5EIsQkLzQjilovKzfNVhX8De6oyE6uHpfFtyBaqUpcl/XzJC/4fjD8vBDyh1zolimIcVrCn9g=="],
+
     "parent-module": ["parent-module@1.0.1", "", { "dependencies": { "callsites": "^3.0.0" } }, "sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g=="],
 
     "parse-entities": ["parse-entities@4.0.2", "", { "dependencies": { "@types/unist": "^2.0.0", "character-entities-legacy": "^3.0.0", "character-reference-invalid": "^2.0.0", "decode-named-character-reference": "^1.0.0", "is-alphanumerical": "^2.0.0", "is-decimal": "^2.0.0", "is-hexadecimal": "^2.0.0" } }, "sha512-GG2AQYWoLgL877gQIKeRPGO1xF9+eG1ujIb5soS5gPvLQ1y2o8FL90w2QWNdf9I361Mpp7726c+lj3U0qK1uGw=="],
@@ -1225,6 +1238,8 @@
 
     "react-dom": ["react-dom@19.2.4", "", { "dependencies": { "scheduler": "^0.27.0" }, "peerDependencies": { "react": "^19.2.4" } }, "sha512-AXJdLo8kgMbimY95O2aKQqsz2iWi9jMgKJhRBAxECE4IFxfcazB2LmzloIoibJI3C12IlY20+KFaLv+71bUJeQ=="],
 
+    "react-icons": ["react-icons@5.5.0", "", { "peerDependencies": { "react": "*" } }, "sha512-MEFcXdkP3dLo8uumGI5xN3lDFNsRtrjbOEKDLD7yv76v4wpnEq2Lt2qeHaQOr34I/wPN3s3+N08WkQ+CW37Xiw=="],
+
     "react-is": ["react-is@16.13.1", "", {}, "sha512-24e6ynE2H+OKt4kqsOvNd8kBpV65zoxbA4BVsEOB3ARVWQki/DHzaUoC5KuON/BiccDaCCTZBuOcfZs70kR8bQ=="],
 
     "react-markdown": ["react-markdown@10.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/mdast": "^4.0.0", "devlop": "^1.0.0", "hast-util-to-jsx-runtime": "^2.0.0", "html-url-attributes": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "remark-parse": "^11.0.0", "remark-rehype": "^11.0.0", "unified": "^11.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0" }, "peerDependencies": { "@types/react": ">=18", "react": ">=18" } }, "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ=="],

package/content/about.mdx

@@ -3,6 +3,7 @@ title: "About Amytis"
 date: "2026-01-07"
 excerpt: "Learn more about the philosophy and technology behind this digital garden."
 layout: "simple"
+toc: true
 ---
 
 # About the Garden

package/content/about.zh.mdx

@@ -0,0 +1,21 @@
+---
+title: "关于 Amytis"
+date: "2026-01-07"
+excerpt: "了解这座数字花园背后的理念与技术。"
+layout: "simple"
+---
+
+Amytis 是一座为长期思想培育而设计的数字花园。与博客不同，数字花园是一个持续演化的想法网络。
+
+## 技术栈
+
+- **Next.js 15+** — 基础框架
+- **Tailwind CSS v4** — 样式系统
+- **MDX** — 支持 React 组件的富内容格式
+- **Bun** — 极速开发体验
+
+## 理念
+
+我们相信**公开学习**的力量。这里是种下种子（初始笔记）、悉心耕耘（提炼与关联）、最终长成长青文章的地方。
+
+> "花园是最好的老师。它教人耐心与细心观察，教人勤劳与节俭，尤其教人全然的信任。" — Gertrude Jekyll

package/content/flows/2026/02/20.md

@@ -0,0 +1,16 @@
+---
+title: "Multimedia embeds in markdown"
+tags: ["video", "podcast", "markdown", "web"]
+---
+
+Tested multimedia embedding in Amytis today. Since `rehype-raw` is enabled, standard HTML `<iframe>`, `<video>`, and `<audio>` tags work directly inside Markdown — no plugins needed.
+
+A few patterns that work well:
+
+- **YouTube / Vimeo** — wrap in a `padding-bottom: 56.25%` container for responsive 16:9
+- **Spotify / Apple Podcasts** — fixed height iframes (152px for compact, 352px for full player)
+- **HTML5 `<video>`** — fully native, supports `poster`, `loop`, `autoplay muted`
+- **HTML5 `<audio>`** — great for podcast episodes or background music samples
+- **Twitch** — needs the `parent` query param set to your domain
+
+The `loading="lazy"` attribute is underused — always worth adding to below-the-fold embeds to keep the initial page fast.

package/content/links.mdx

@@ -0,0 +1,42 @@
+---
+title: "Links"
+date: "2026-01-01"
+excerpt: "A curated collection of resources, tools, and friends on the web."
+layout: "simple"
+toc: true
+---
+
+A living collection of places worth visiting — useful resources I return to, and friends whose writing I admire.
+
+---
+
+## Resources
+
+### Writing & Thinking
+
+- [Zettelkasten Method](https://zettelkasten.de/) — The definitive guide to networked note-taking and knowledge management.
+- [Andy Matuschak's Notes](https://notes.andymatuschak.org/) — A public working notebook from a researcher in tools for thought.
+- [LessWrong](https://www.lesswrong.com/) — A community blog focused on rationality and careful reasoning.
+
+### Development
+
+- [MDN Web Docs](https://developer.mozilla.org/) — The most reliable reference for web platform APIs.
+- [The Changelog](https://changelog.com/) — Podcasts and news for developers following open-source software.
+- [Hacker News](https://news.ycombinator.com/) — Technology news and community discussion curated by Y Combinator.
+
+### Design
+
+- [Refactoring UI](https://www.refactoringui.com/) — Practical design advice for developers, by the creators of Tailwind CSS.
+- [Sidebar.io](https://sidebar.io/) — Five design links every day, covering UI, typography, and visual inspiration.
+
+---
+
+## Friends
+
+- [Example Blog](https://example.com/) — A thoughtful writer exploring the intersection of technology and everyday life.
+- [Another Garden](https://example.com/) — Beautifully tended digital garden with notes on philosophy and code.
+- [Friend's Site](https://example.com/) — Short-form essays on creativity, craft, and the making of things.
+
+---
+
+*Know a link that belongs here? [Send it my way](/about).*

package/content/links.zh.mdx

@@ -0,0 +1,41 @@
+---
+title: "链接"
+date: "2026-01-01"
+excerpt: "精选资源、工具与友情链接。"
+layout: "simple"
+---
+
+持续更新的精选集合——常常造访的实用资源，以及值得关注的朋友们。
+
+---
+
+## 资源
+
+### 写作与思考
+
+- [卡片盒笔记法](https://zettelkasten.de/) — 网络化笔记与知识管理的权威指南。
+- [Andy Matuschak 的笔记](https://notes.andymatuschak.org/) — 思维工具研究者的公开工作笔记本。
+- [LessWrong](https://www.lesswrong.com/) — 专注于理性思维的社区博客。
+
+### 开发
+
+- [MDN Web Docs](https://developer.mozilla.org/) — 最可靠的 Web 平台 API 参考文档。
+- [The Changelog](https://changelog.com/) — 面向开发者的开源软件播客与资讯。
+- [Hacker News](https://news.ycombinator.com/) — Y Combinator 精选的技术资讯与社区讨论。
+
+### 设计
+
+- [Refactoring UI](https://www.refactoringui.com/) — Tailwind CSS 作者出品的开发者实用设计指南。
+- [Sidebar.io](https://sidebar.io/) — 每日五条设计链接，涵盖 UI、排版与视觉灵感。
+
+---
+
+## 朋友们
+
+- [示例博客](https://example.com/) — 探索技术与日常生活交汇点的深度写作者。
+- [另一座花园](https://example.com/) — 关于哲学与代码的精心耕耘的数字花园。
+- [朋友的站点](https://example.com/) — 关于创造、手艺与制作过程的短篇随笔。
+
+---
+
+*有好链接想推荐？[告诉我](/about)。*

package/content/posts/2026-02-20-i18n-routing-considerations.mdx

@@ -0,0 +1,150 @@
+---
+title: "i18n in a Static Next.js Blog: Client-Side Toggle vs URL-Based Routing"
+date: "2026-02-20"
+excerpt: "A deep dive into the trade-offs between client-side language switching and proper URL-based locale routing for a statically exported Next.js digital garden."
+tags: ["nextjs", "i18n", "seo", "static-site"]
+---
+
+When building a multilingual static blog with Next.js, there are two fundamentally different approaches to internationalisation. Choosing between them involves trade-offs across SEO, developer experience, content strategy, and hosting complexity.
+
+## The Client-Side Toggle Approach
+
+The simplest approach stores language preference in client state and resolves translations after hydration:
+
+```tsx
+// Language stored in context, resolved on the client
+const { t, language } = useLanguage();
+const label = t('about'); // "About" or "关于"
+```
+
+For page content that has locale variants, all versions are server-rendered into the HTML and a thin client wrapper toggles visibility:
+
+```tsx
+// LocaleSwitch: shows/hides [data-locale] divs via useEffect
+<LocaleSwitch>
+  <div data-locale="en"><MarkdownRenderer content={enContent} /></div>
+  <div data-locale="zh" style={{ display: 'none' }}><MarkdownRenderer content={zhContent} /></div>
+</LocaleSwitch>
+```
+
+This works and is zero-config — no routing changes needed. But it has real limitations.
+
+### SEO Problems
+
+- **Crawlers always see the default language.** Googlebot doesn't execute `localStorage` reads, so it always indexes the default locale's content.
+- **`display:none` content is risky.** Google may partially index hidden locale variants, or ignore them entirely.
+- **No `hreflang` signals.** Search engines can't discover alternate language versions of a page.
+- **`<html lang>` not updated.** Accessibility and search engine tooling rely on this attribute.
+
+---
+
+## URL-Based Locale Routing
+
+The proper solution gives each language variant its own URL:
+
+```
+/about        → English (default, no prefix)
+/zh/about     → Chinese
+```
+
+With Next.js App Router, this means moving all routes under an `app/[locale]/` segment and using `generateStaticParams` to pre-render each route for each locale at build time.
+
+Since Amytis uses `output: "export"`, this is pure **Static Site Generation** — the HTML is fully pre-built per locale. Crawlers get complete HTML with no JavaScript required, and each locale is independently indexable.
+
+### The Default Locale Prefix Problem
+
+Most sites want the default locale to have a clean URL (`/about`, not `/en/about`). With a runtime server, middleware handles this transparently. With static export, you need your **hosting layer** to do the rewrite.
+
+#### Netlify / Cloudflare Pages
+
+Drop a `_redirects` file in `public/`:
+
+```
+/en              /            301
+/en/*            /:splat      301
+/*               /en/:splat   200
+```
+
+The `200` status is a **silent rewrite** — the user sees `/about` in the URL bar, but the server serves `out/en/about/index.html`.
+
+#### Vercel
+
+```json
+{
+  "redirects": [
+    { "source": "/en/:path*", "destination": "/:path*", "permanent": true }
+  ],
+  "rewrites": [
+    { "source": "/((?!zh/).*)", "destination": "/en/$1" }
+  ]
+}
+```
+
+#### Nginx
+
+```nginx
+location ~ ^/en(/.*)?$ { return 301 ${1:-/}; }
+location /zh/ { try_files $uri $uri/index.html =404; }
+location / { try_files /en$uri /en$uri/index.html =404; }
+```
+
+#### GitHub Pages
+
+GitHub Pages has no native rewrite support. The simplest workaround is a root `index.html` with a JS language detector:
+
+```html
+<script>
+  const lang = navigator.language.startsWith('zh') ? 'zh' : 'en';
+  window.location.replace('/' + lang + '/');
+</script>
+```
+
+Or just accept the `/en/` prefix for all locales.
+
+---
+
+## Content Strategy
+
+URL-based routing changes more than just URLs — it changes how you think about content.
+
+For a personal digital garden, most content is written in one language and won't be fully translated. The realistic scope is:
+
+| Content Type | Translated? | Approach |
+|---|---|---|
+| Static pages (about, privacy) | Yes | Optional `.zh.mdx` variant files |
+| Posts | Rarely | Fallback to original + notice |
+| Series descriptions | Maybe | Optional `index.zh.mdx` |
+| Books | Unlikely | Fallback |
+| Flows (daily notes) | No | UI-only i18n, no locale in URL |
+
+The `.{locale}.mdx` convention — already used for static pages in Amytis — extends naturally to posts and series:
+
+```
+content/posts/my-post.mdx           # default locale
+content/posts/my-post.zh.mdx        # optional Chinese translation
+content/series/my-series/index.zh.mdx
+```
+
+At build time, `generateStaticParams` generates `/en/my-post` and `/zh/my-post`. If the `.zh.mdx` file doesn't exist, the Chinese URL falls back to the English content with a small "not available in this language" banner.
+
+---
+
+## Trade-offs at a Glance
+
+| Aspect | Client-Side Toggle | URL-Based Routing |
+|---|---|---|
+| SEO | Crawlers see default lang only | Each locale fully indexed |
+| Default locale prefix | No prefix | CDN rewrite needed |
+| Build size | Same | ~2× |
+| Refactor scope | None | Large |
+| Content strategy | `.zh.mdx` for pages only | `.zh.mdx` for all content types |
+
+---
+
+## Conclusion
+
+For a personal blog where SEO in a second language isn't critical, the client-side toggle approach is pragmatic and gets the job done. UI strings translate, page content can optionally have locale variants, and there's no hosting complexity.
+
+For a project where bilingual SEO matters — where you genuinely want Chinese content indexed under Chinese URLs — URL-based routing is the right architecture. The CDN configuration is a one-time setup, and the `.{locale}.mdx` convention for content is already half-implemented.
+
+The good news: both approaches share the same content file convention. Migrating from client-side toggle to URL-based routing is a routing and build change, not a content restructure.