@hutusi/amytis 1.10.0 → 1.11.0

package/AGENTS.md

@@ -1,21 +1,25 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `tags`, `authors`, feeds, sitemap).
+- `src/app/`: Next.js App Router pages and route handlers (`posts`, `series`, `books`, `flows`, `notes`, `tags`, `authors`, feeds, graph, sitemap, custom `[slug]` routes).
 - `src/components/`: Reusable UI building blocks (cards, navigation, search, i18n/theme controls).
-- `src/lib/`: Content parsing and shared logic (`markdown.ts`, i18n helpers, rehype utilities).
-- `content/posts/`, `content/series/`: Markdown/MDX source content. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
+- `src/lib/`: Content parsing and shared logic (`markdown.ts`, feed helpers, URL helpers, rehype/remark utilities).
+- `content/`: Markdown/MDX source content for posts, series, books, notes, flows, and static pages. Use folder posts (`index.mdx` + `images/` or `assets/`) when media is co-located.
 - `tests/`: Integration/e2e/tooling suites; keep focused utility tests near source (example: `src/lib/markdown.test.ts`).
 - `scripts/`: Bun-based authoring/import tooling.
+- `packages/create-amytis/`: The `bun create amytis` scaffold CLI; keep its tests aligned with repo scaffolding behavior.
 
 ## Build, Test, and Development Commands
 - `bun install`: Install dependencies.
 - `bun dev`: Run local dev server at `http://localhost:3000`.
-- `bun run build`: Production export build (asset copy + Next build + image optimizer).
-- `bun run build:dev`: Build without export image optimization.
-- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`).
+- `bun run build`: Production export build (copy assets, generate graph, Next build, optimize images, generate Pagefind index in `out/pagefind`).
+- `bun run build:dev`: Build without export image optimization and generate the dev search index in `public/pagefind`.
+- `bun run build:graph`: Regenerate the knowledge graph data.
+- `bun run validate`: Run the recommended pre-PR validation sequence (`lint`, `test`, `build:dev`).
+- `bun run clean`: Remove generated outputs (`.next`, `out`, `public/posts`, `public/books`, `public/flows`).
 - `bun run lint`: Run ESLint.
 - `bun test` / `bun run test:unit` / `bun run test:int` / `bun run test:e2e`: Run all or scoped tests.
+- 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`.
 
 ## Coding Style & Naming Conventions
 - Use TypeScript for app and utility code; MDX/Markdown for content.
@@ -27,12 +31,14 @@
 - 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.
 - When touching dynamic routes, verify both ASCII and Unicode paths.
 
 ## Testing Guidelines
 - Test framework: Bun (`bun:test`). File pattern: `*.test.ts`.
-- Add tests when changing slug resolution, content parsing, routing, or scaffolding scripts.
+- Add tests when changing slug resolution, content parsing, routing, feed generation, or scaffolding scripts.
 - Before PR: run `bun run lint && bun test && bun run build:dev`.
+- Search in local dev depends on the Pagefind output from `bun run build:dev`; regenerate it when changing content or search behavior.
 
 ## Commit & Pull Request Guidelines
 - Follow Conventional Commits used in history (`feat:`, `fix:`, `refactor:`, `docs:`, `release:`).

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.11.0] - 2026-03-07
+
+### Changed
+- **Feed Output Quality**: RSS and Atom feeds now render Markdown content as HTML, include richer item metadata, and send explicit cache headers for static deployments.
+- **Metadata Consistency**: Consolidated image URL resolution so Open Graph and JSON-LD metadata use the same asset handling logic.
+- **Documentation Sync**: Updated the English and Chinese READMEs plus contributor guidance to reflect current scaffolding behavior, dev-search setup, and workspace instructions.
+
+### Fixed
+- **RSS Standards Compliance**: Corrected the RSS MIME type to `application/rss+xml` and improved RSS/Atom structure for better reader compatibility.
+- **Feed Metadata Fidelity**: Improved handling of author fields, item content, and image metadata across feed generation and social preview output.
+- **Post Page Polish**: Improved post page OG images, previous/next navigation consistency, and TOC indentation.
+- **Book Link Consistency**: Standardized book links to use the shared URL helper.
+
+### Docs
+- **Developer Notes**: Added inline documentation for `getFeedItems()` behavior and configuration handling.
+- **Repository Instructions**: Refreshed repository-level agent instructions to match the current workspace layout and release workflow.
+
 ## [1.10.0] - 2026-03-02
 
 ### Added

package/CLAUDE.md

@@ -96,6 +96,15 @@ bun run sync-book <slug>              # Sync chapters list for one book
 
 Date-prefixed filenames (`2026-01-01-my-post.mdx`) extract dates automatically.
 
+## Config Files
+
+There are two config files that must be kept in sync:
+
+- **`site.config.ts`** — the live config for this repo (i18n enabled; locale-aware fields use `{ en: '...', zh: '...' }` objects)
+- **`site.config.example.ts`** — single-language starter template shipped via `create-amytis`; locale-aware fields use plain strings; optional features (books, flow) default to disabled
+
+**Rule:** Any schema change to `site.config.ts` (new field, renamed field, type change) must be mirrored in `site.config.example.ts`. Locale-aware values (`string | Record<string, string>`) should use plain strings in the example.
+
 ## Configuration (`site.config.ts`)
 
 Key configuration options:
@@ -109,8 +118,12 @@ Key configuration options:
 - `i18n` - Default locale and supported locales
 - `featured.series` - Scrollable series: `scrollThreshold` (default: 2), `maxItems` (default: 6)
 - `featured.stories` - Scrollable stories: `scrollThreshold` (default: 1), `maxItems` (default: 5)
-- `analytics.provider` - 'umami' | 'plausible' | 'google' | null
+- `analytics.providers` - array of enabled providers: `['umami', 'google']`; `[]` disables analytics
 - `comments.provider` - 'giscus' | 'disqus' | null
+- `feed.format` - 'rss' | 'atom' | 'both'
+- `feed.content` - 'full' | 'excerpt'
+- `feed.maxItems` - max feed items (0 = unlimited)
+- `footer.bottomLinks` - custom links in the footer bottom bar (ICP, cookie policy, etc.); `text` accepts plain string or `{ en, zh }` locale map
 - `posts.basePath` - Custom URL prefix for all posts (default: `'posts'`); e.g. `'articles'` → posts at `/articles/[slug]`
 - `posts.authors.default` - Fallback authors when a post has none set in frontmatter
 - `posts.authors.showInHeader` - Show author byline below post title (default: true)
@@ -125,6 +138,7 @@ Key configuration options:
 ```yaml
 ---
 title: "Post Title"
+subtitle: "Optional subtitle line"  # Rendered below the title in italic
 date: "2026-01-01"
 excerpt: "Optional summary (auto-generated if omitted)"
 category: "Category Name"

package/README.md

@@ -6,7 +6,7 @@
 
 [**Live Demo**](https://amytis.vercel.app/)
 
-![Amytis Screenshot](public/screenshot.png)
+![Amytis Screenshot](public/images/amytis-screenshot.jpg)
 
 ## The Knowledge Ladder
 
@@ -50,9 +50,13 @@ Each stage builds on the previous one, so your garden can evolve naturally.
   - Co-located assets: keep images inside post folders (`./images/`).
   - Date-prefixed filenames: `2026-01-01-my-post.mdx`.
   - Draft support for posts, series, books, and flows.
+- **Author Ecosystem:** Per-author profile pages with bio, avatar, and social links. Posts are filterable by author; an optional author card appears at the end of each post.
 - **Performance & SEO:**
   - Fully static export with optimized WebP images.
-  - Native sitemap and RSS feed generation.
+  - Open Graph and Twitter card metadata for every content type.
+  - JSON-LD structured data (`BlogPosting`, `Book`, `Article`) for Google rich results.
+  - RSS/Atom feed with configurable format (`rss` | `atom` | `both`) and content depth (`full` | `excerpt`).
+  - Feed auto-discovery links in `<head>`, native sitemap generation.
   - Multilingual reading time estimate (supports Latin and CJK).
 - **Integrations:**
   - Analytics: Umami, Plausible, or Google Analytics.
@@ -71,6 +75,20 @@ Each stage builds on the previous one, so your garden can evolve naturally.
 
 ## Quick Start
 
+### New Project (Recommended)
+
+Scaffold a new Amytis site with one command:
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+The scaffold command downloads the latest tagged Amytis release, installs dependencies, and patches `site.config.ts` and `package.json` with your project metadata.
+
+### Clone & Run
+
 1. **Install Dependencies:**
    ```bash
    bun install
@@ -82,6 +100,8 @@ Each stage builds on the previous one, so your garden can evolve naturally.
    ```
    Visit [http://localhost:3000](http://localhost:3000).
 
+   > **Search in dev:** the Pagefind index is generated during `bun run build:dev`. Run it once before testing Cmd/Ctrl+K locally, and re-run it after content changes.
+
 3. **Build for Production (Static Export):**
    ```bash
    bun run build
@@ -115,6 +135,7 @@ bun run test:e2e
 
 ## Create Content
 bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
 bun run new-series "Series Name"
 bun run new-note "Concept"
 bun run new-flow
@@ -204,6 +225,8 @@ amytis/
     components/         # React components
     lib/
       markdown.ts       # Data access layer
+  packages/
+    create-amytis/      # `bun create amytis` scaffold CLI
   site.config.ts        # Site configuration
 ```
 

package/README.zh.md

@@ -6,7 +6,7 @@
 
 [**在线演示**](https://amytis.vercel.app/)
 
-![Amytis 截图](public/screenshot.png)
+![Amytis 截图](public/images/amytis-screenshot.jpg)
 
 ## 知识阶梯
 
@@ -43,9 +43,13 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
   - 自动系统主题检测（明/暗）
   - 四套配色主题：default、blue、rose、amber
   - 吸顶目录与阅读进度跟踪
+- **作者生态**：每位作者有独立主页，包含简介、头像与社交链接。文章支持按作者筛选，并可在文末显示作者卡片。
 - **性能与 SEO**：
   - 全静态导出与 WebP 优化
-  - 自动 sitemap 与 RSS
+  - 每种内容类型均有完整的 Open Graph 与 Twitter Card 元数据
+  - JSON-LD 结构化数据（`BlogPosting`、`Book`、`Article`），支持 Google 富媒体搜索结果
+  - RSS/Atom 订阅源，格式（`rss` | `atom` | `both`）与内容深度（`full` | `excerpt`）可配置
+  - `<head>` 自动注入 Feed 发现链接，原生 sitemap 生成
   - 支持 Latin/CJK 的多语言阅读时长估算
 - **集成能力**：
   - 统计：Umami / Plausible / Google Analytics
@@ -62,6 +66,20 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
 
 ## 快速开始
 
+### 新建项目（推荐）
+
+一条命令创建新的 Amytis 站点：
+
+```bash
+bun create amytis my-garden
+cd my-garden
+bun dev
+```
+
+该脚手架会下载最新发布版 Amytis，自动安装依赖，并根据你的项目信息更新 `site.config.ts` 和 `package.json`。
+
+### 克隆运行
+
 1. **安装依赖**
    ```bash
    bun install
@@ -73,6 +91,8 @@ Amytis 围绕一条从粗糙到精炼的知识路径构建：
    ```
    打开 [http://localhost:3000](http://localhost:3000)。
 
+   > **本地搜索说明：** Pagefind 索引是在执行 `bun run build:dev` 时生成的。本地测试 Cmd/Ctrl+K 前先运行一次；内容更新后也需要重新生成。
+
 3. **生产构建（静态导出）**
    ```bash
    bun run build
@@ -106,6 +126,7 @@ bun run test:e2e
 
 ## Create Content
 bun run new "Post Title"
+bun run new-weekly "Weekly Topic"
 bun run new-series "Series Name"
 bun run new-note "Concept"
 bun run new-flow
@@ -157,6 +178,8 @@ amytis/
     app/
     components/
     lib/
+  packages/
+    create-amytis/
   site.config.ts
 ```
 

package/TODO.md

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

package/bun.lock

@@ -11,6 +11,7 @@
         "github-slugger": "^2.0.0",
         "gray-matter": "^4.0.3",
         "image-size": "^2.0.2",
+        "katex": "^0.16.33",
         "mermaid": "^11.12.3",
         "next": "16.1.6",
         "next-image-export-optimizer": "^1.20.1",
@@ -23,8 +24,12 @@
         "rehype-katex": "^7.0.1",
         "rehype-raw": "^7.0.0",
         "rehype-slug": "^6.0.0",
+        "rehype-stringify": "^10.0.1",
         "remark-gfm": "^4.0.1",
         "remark-math": "^6.0.0",
+        "remark-parse": "^11.0.0",
+        "remark-rehype": "^11.1.2",
+        "unified": "^11.0.5",
         "unist-util-visit": "^5.1.0",
         "zod": "^4.3.6",
       },
@@ -32,7 +37,9 @@
         "@tailwindcss/postcss": "^4.1.18",
         "@types/bun": "^1.3.9",
         "@types/d3": "^7.4.3",
+        "@types/hast": "^3.0.4",
         "@types/image-size": "^0.8.0",
+        "@types/mdast": "^4.0.4",
         "@types/node": "^24.10.13",
         "@types/react": "^19.2.14",
         "@types/react-dom": "^19.2.3",
@@ -46,6 +53,13 @@
         "typescript": "^5.9.3",
       },
     },
+    "packages/create-amytis": {
+      "name": "create-amytis",
+      "version": "0.1.0",
+      "bin": {
+        "create-amytis": "./dist/index.js",
+      },
+    },
   },
   "trustedDependencies": [
     "sharp",
@@ -558,7 +572,7 @@
 
     "comma-separated-tokens": ["comma-separated-tokens@2.0.3", "", {}, "sha512-Fu4hJdvzeylCfQPp9SGWidpzrMs7tTrlu6Vb8XGaRGck8QSNZJJp538Wrb60Lax4fPwR64ViY468OIUTbRlGZg=="],
 
-    "commander": ["commander@7.2.0", "", {}, "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw=="],
+    "commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
 
     "concat-map": ["concat-map@0.0.1", "", {}, "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg=="],
 
@@ -568,6 +582,8 @@
 
     "cose-base": ["cose-base@1.0.3", "", { "dependencies": { "layout-base": "^1.0.0" } }, "sha512-s9whTXInMSgAp/NVXVNuVxVKzGH2qck3aQlVHxDCdAEPgtMKwc4Wq6/QKhgdEdgbLSi9rBTAcPoRa6JpiG4ksg=="],
 
+    "create-amytis": ["create-amytis@workspace:packages/create-amytis"],
+
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
 
     "cssesc": ["cssesc@3.0.0", "", { "bin": { "cssesc": "bin/cssesc" } }, "sha512-/Tb/JcjK111nNScGob5MNtsntNM1aCNUDipB/TkwZFhyDrrE47SOx/18wF2bbjgc3ZzCSKW1T5nt5EbFoAz/Vg=="],
@@ -842,6 +858,8 @@
 
     "hast-util-raw": ["hast-util-raw@9.1.0", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "@ungap/structured-clone": "^1.0.0", "hast-util-from-parse5": "^8.0.0", "hast-util-to-parse5": "^8.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "parse5": "^7.0.0", "unist-util-position": "^5.0.0", "unist-util-visit": "^5.0.0", "vfile": "^6.0.0", "web-namespaces": "^2.0.0", "zwitch": "^2.0.0" } }, "sha512-Y8/SBAHkZGoNkpzqqfCldijcuUKh7/su31kEBp67cFY09Wy0mTRgtsLYsiIxMJxlu0f6AA5SUTbDR8K0rxnbUw=="],
 
+    "hast-util-to-html": ["hast-util-to-html@9.0.5", "", { "dependencies": { "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "ccount": "^2.0.0", "comma-separated-tokens": "^2.0.0", "hast-util-whitespace": "^3.0.0", "html-void-elements": "^3.0.0", "mdast-util-to-hast": "^13.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "stringify-entities": "^4.0.0", "zwitch": "^2.0.4" } }, "sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw=="],
+
     "hast-util-to-jsx-runtime": ["hast-util-to-jsx-runtime@2.3.6", "", { "dependencies": { "@types/estree": "^1.0.0", "@types/hast": "^3.0.0", "@types/unist": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "estree-util-is-identifier-name": "^3.0.0", "hast-util-whitespace": "^3.0.0", "mdast-util-mdx-expression": "^2.0.0", "mdast-util-mdx-jsx": "^3.0.0", "mdast-util-mdxjs-esm": "^2.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "style-to-js": "^1.0.0", "unist-util-position": "^5.0.0", "vfile-message": "^4.0.0" } }, "sha512-zl6s8LwNyo1P9uw+XJGvZtdFF1GdAkOg8ujOw+4Pyb76874fLps4ueHXDhXWdk6YHQ6OgUtinliG7RsYvCbbBg=="],
 
     "hast-util-to-parse5": ["hast-util-to-parse5@8.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "comma-separated-tokens": "^2.0.0", "devlop": "^1.0.0", "property-information": "^7.0.0", "space-separated-tokens": "^2.0.0", "web-namespaces": "^2.0.0", "zwitch": "^2.0.0" } }, "sha512-MlWT6Pjt4CG9lFCjiz4BH7l9wmrMkfkJYCxFwKQic8+RTZgWPuWxwAfjJElsXkex7DJjfSJsQIt931ilUgmwdA=="],
@@ -970,7 +988,7 @@
 
     "jsx-ast-utils": ["jsx-ast-utils@3.3.5", "", { "dependencies": { "array-includes": "^3.1.6", "array.prototype.flat": "^1.3.1", "object.assign": "^4.1.4", "object.values": "^1.1.6" } }, "sha512-ZZow9HBI5O6EPgSJLUb8n2NKgmVWTwCvHGwFuJlMjvLFqlGG6pjirPhtdsseaLZjSibD8eegzmYpUZwoIlj2cQ=="],
 
-    "katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+    "katex": ["katex@0.16.33", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-q3N5u+1sY9Bu7T4nlXoiRBXWfwSefNGoKeOwekV+gw0cAXQlz2Ww6BLcmBxVDeXBMUDQv6fK5bcNaJLxob3ZQA=="],
 
     "keyv": ["keyv@4.5.4", "", { "dependencies": { "json-buffer": "3.0.1" } }, "sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw=="],
 
@@ -1260,6 +1278,8 @@
 
     "rehype-slug": ["rehype-slug@6.0.0", "", { "dependencies": { "@types/hast": "^3.0.0", "github-slugger": "^2.0.0", "hast-util-heading-rank": "^3.0.0", "hast-util-to-string": "^3.0.0", "unist-util-visit": "^5.0.0" } }, "sha512-lWyvf/jwu+oS5+hL5eClVd3hNdmwM1kAC0BUvEGD19pajQMIzcNUd/k9GsfQ+FfECvX+JE+e9/btsKH0EjJT6A=="],
 
+    "rehype-stringify": ["rehype-stringify@10.0.1", "", { "dependencies": { "@types/hast": "^3.0.0", "hast-util-to-html": "^9.0.0", "unified": "^11.0.0" } }, "sha512-k9ecfXHmIPuFVI61B9DeLPN0qFHfawM6RsuX48hoqlaKSF61RskNjSm1lI8PhBEM0MRdLxVVm4WmTqJQccH9mA=="],
+
     "remark-gfm": ["remark-gfm@4.0.1", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-gfm": "^3.0.0", "micromark-extension-gfm": "^3.0.0", "remark-parse": "^11.0.0", "remark-stringify": "^11.0.0", "unified": "^11.0.0" } }, "sha512-1quofZ2RQ9EWdeN34S79+KExV1764+wCUGop5CPL1WGdD0ocPpu91lzPGbwWMECpEpd42kJGQwzRfyov9j4yNg=="],
 
     "remark-math": ["remark-math@6.0.0", "", { "dependencies": { "@types/mdast": "^4.0.0", "mdast-util-math": "^3.0.0", "micromark-extension-math": "^3.0.0", "unified": "^11.0.0" } }, "sha512-MMqgnP74Igy+S3WwnhQ7kqGlEerTETXMvJhrUzDikVZ2/uogJCb+WHUg97hK9/jcfc0dkD73s3LN8zU49cTEtA=="],
@@ -1504,6 +1524,8 @@
 
     "cytoscape-fcose/cose-base": ["cose-base@2.2.0", "", { "dependencies": { "layout-base": "^2.0.0" } }, "sha512-AzlgcsCbUMymkADOJtQm3wO9S3ltPfYOFD5033keQn9NJzIbtnZj+UdBJe7DYml/8TdbtHJW3j58SOnKhWY/5g=="],
 
+    "d3-dsv/commander": ["commander@7.2.0", "", {}, "sha512-QrWXB+ZQSVPmIWIhtEO9H+gwHaMGYiF5ChvoJ+K9ZGHG/sVsa6yiesAD1GC/x46sET00Xlwo1u49RVVVzvcSkw=="],
+
     "d3-sankey/d3-array": ["d3-array@2.12.1", "", { "dependencies": { "internmap": "^1.0.0" } }, "sha512-B0ErZK/66mHtEsR1TkPEEkwdy+WDesimkM5gpZr5Dsg54BiTA5RXtYW5qTLIAcekaS9xfZrzBLF/OAkB3Qn1YQ=="],
 
     "d3-sankey/d3-shape": ["d3-shape@1.3.7", "", { "dependencies": { "d3-path": "1" } }, "sha512-EUkvKjqPFUAZyOlhY5gzCxCeI0Aep04LwIRpsZ/mLFelJiUfnK56jo5JMDSE7yyP2kLSb6LtF+S5chMk7uqPqw=="],
@@ -1520,16 +1542,20 @@
 
     "is-bun-module/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
-    "katex/commander": ["commander@8.3.0", "", {}, "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="],
-
     "mdast-util-find-and-replace/escape-string-regexp": ["escape-string-regexp@5.0.0", "", {}, "sha512-/veY75JbMK4j1yjvuUxuVsiS/hr/4iHs9FTT6cgTexxdE0Ly/glccBAkloH/DofkjRbZU3bnoj38mOmhkZ0lHw=="],
 
+    "mermaid/katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+
+    "micromark-extension-math/katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+
     "micromatch/picomatch": ["picomatch@2.3.1", "", {}, "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA=="],
 
     "next/postcss": ["postcss@8.4.31", "", { "dependencies": { "nanoid": "^3.3.6", "picocolors": "^1.0.0", "source-map-js": "^1.0.2" } }, "sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ=="],
 
     "parse-entities/@types/unist": ["@types/unist@2.0.11", "", {}, "sha512-CmBKiL6NNo/OqgmMn95Fk9Whlp2mtvIv+KNpQKN2F4SjvrEesubTRWGYSg+BnWZOnlCaSTU1sMpsBOzgbYhnsA=="],
 
+    "rehype-katex/katex": ["katex@0.16.28", "", { "dependencies": { "commander": "^8.3.0" }, "bin": { "katex": "cli.js" } }, "sha512-YHzO7721WbmAL6Ov1uzN/l5mY5WWWhJBSW+jq4tkfZfsxmo1hu6frS0EOswvjBUnWE6NtjEs48SFn5CQESRLZg=="],
+
     "sharp/semver": ["semver@7.7.3", "", { "bin": { "semver": "bin/semver.js" } }, "sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q=="],
 
     "@eslint/eslintrc/js-yaml/argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],

package/content/posts/2026-01-21-kitchen-sink/index.mdx

@@ -7,7 +7,7 @@ tags: ["features", "test", "demo"]
 authors: ["Amytis Team", "Tester"]
 layout: "post"
 latex: true
-toc: false
+toc: true
 ---
 
 # Heading Level 1
@@ -128,6 +128,31 @@ sequenceDiagram
 ### Raw HTML (Quoted)
 <img src="./assets/test.svg" width="100" alt="Small HTML Image" style="border: 2px solid #ccc; border-radius: 8px;" />
 
+### Photos from Public Directory
+
+![Antelope Canyon](/images/antelope-canyon.jpg)
+
+![Mountain Landscape](/images/mountains.jpg)
+
+![Lake View](/images/lake.jpg)
+
+![Flowers](/images/flowers.jpg)
+
+![Cappadocia](/images/cappadocia.jpg)
+
+![Galaxy](/images/galaxy.jpg)
+
+### Vibrant Waves (AVIF format)
+
+![Vibrant Waves](/images/vibrant-waves.avif)
+
+### Side by Side (Raw HTML)
+
+<div style="display: flex; gap: 1rem; flex-wrap: wrap;">
+  <img src="/images/antelope-canyon.jpg" alt="Antelope Canyon" style="width: 48%; border-radius: 8px;" />
+  <img src="/images/cappadocia.jpg" alt="Cappadocia" style="width: 48%; border-radius: 8px;" />
+</div>
+
 ---
 
 ## Tables

package/docs/CONTRIBUTING.md

@@ -93,7 +93,9 @@ bun run series-draft "my-series" --undraft
 ```bash
 bun test                   # Run all tests
 bun run test:unit          # Run unit tests
+bun run test:int           # Run integration tests
 bun run test:e2e           # Run end-to-end tests
+bun run validate           # Lint + test + build:dev
 ```
 
 ## Building

package/docs/DIGITAL_GARDEN.md

@@ -53,7 +53,7 @@ Flows are a stream-style collection of daily notes, micro-blogging, or imported
 
 ## Configuration
 
-In `site.config.ts`, ensure flow features are enabled (the graph and notes surfaces are flow-related in current routing):
+Flows are controlled by `site.config.ts`, while notes and the graph are always routed when corresponding content exists:
 
 ```typescript
 export const siteConfig = {
@@ -66,3 +66,9 @@ export const siteConfig = {
   }
 };
 ```
+
+Related settings that shape the digital-garden experience live alongside that flag:
+
+- `flows.recentCount`: controls how many flow entries appear on the homepage.
+- `pagination.flows` and `pagination.notes`: control listing page sizes.
+- `homepage.sections`: lets you enable, disable, or reorder homepage sections such as recent flows.

package/eslint.config.mjs

@@ -14,6 +14,8 @@ const eslintConfig = defineConfig([
     "next-env.d.ts",
     // Generated at build time — not authored code
     "public/pagefind/**",
+    // Package compiled output — not authored code
+    "packages/*/dist/**",
   ]),
 ]);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hutusi/amytis",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "A high-performance digital garden and blog engine with Next.js 16 and Tailwind CSS v4",
   "repository": {
     "type": "git",
@@ -33,8 +33,8 @@
     "deploy": "bun scripts/deploy.ts",
     "start": "next start",
     "lint": "eslint",
-    "test": "bun test src tests/unit tests/tooling && bun run test:int",
-    "test:unit": "bun test src tests/unit",
+    "test": "bun test src tests/unit tests/tooling packages/create-amytis/src && bun run test:int",
+    "test:unit": "bun test src tests/unit packages/create-amytis/src",
     "test:int": "bun test tests/integration",
     "test:e2e": "bun test tests/e2e"
   },
@@ -45,6 +45,7 @@
     "github-slugger": "^2.0.0",
     "gray-matter": "^4.0.3",
     "image-size": "^2.0.2",
+    "katex": "^0.16.33",
     "mermaid": "^11.12.3",
     "next": "16.1.6",
     "next-image-export-optimizer": "^1.20.1",
@@ -57,8 +58,12 @@
     "rehype-katex": "^7.0.1",
     "rehype-raw": "^7.0.0",
     "rehype-slug": "^6.0.0",
+    "rehype-stringify": "^10.0.1",
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "zod": "^4.3.6"
   },
@@ -66,7 +71,9 @@
     "@tailwindcss/postcss": "^4.1.18",
     "@types/bun": "^1.3.9",
     "@types/d3": "^7.4.3",
+    "@types/hast": "^3.0.4",
     "@types/image-size": "^0.8.0",
+    "@types/mdast": "^4.0.4",
     "@types/node": "^24.10.13",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -86,5 +93,6 @@
   "trustedDependencies": [
     "sharp",
     "unrs-resolver"
-  ]
+  ],
+  "workspaces": ["packages/*"]
 }

package/packages/create-amytis/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "create-amytis",
+  "version": "0.1.0",
+  "description": "Create a new Amytis digital garden",
+  "license": "MIT",
+  "bin": { "create-amytis": "./dist/index.js" },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target node --sourcemap=none",
+    "dev": "bun src/index.ts",
+    "test": "bun test src"
+  },
+  "files": ["dist"]
+}