@hutusi/amytis 1.11.0 → 1.12.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,29 @@ 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.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

@@ -119,6 +119,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 +133,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 +146,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 +166,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 +186,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 +258,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 +271,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 +283,7 @@ amytis/
 - [Deployment Guide](docs/deployment.md)
 - [Digital Garden Guide](docs/DIGITAL_GARDEN.md)
 - [Contributing Guide](docs/CONTRIBUTING.md)
+- [Troubleshooting](docs/TROUBLESHOOTING.md)
 
 ## License
 

package/README.zh.md

@@ -110,6 +110,7 @@ bun dev
 ## Core
 bun dev
 bun run lint
+bun run build:graph
 bun run validate
 
 ## Build & Deploy
@@ -123,6 +124,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"
@@ -135,9 +137,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
 ```
 
 ### 导入聊天记录到 Flows
@@ -153,15 +157,37 @@ bun run new-flow-from-chat
 
 ## 配置
 
-所有站点配置集中在 `site.config.ts`。
+主要站点配置集中在 `site.config.ts`，`site.config.example.ts` 则是更完整的参考模板，适合查看可选项和默认写法。
+
+优先关注这些配置区块：
+
+- 站点信息：`title`、`description`、`baseUrl`、`ogImage`、`logo`
+- 导航与页脚：`nav`、`footer`、`subscribe`、`social`
+- 内容路由：`posts.basePath`、`posts.includeDateInUrl`、`series.autoPaths`、`series.customPaths`
+- 首页结构：`hero`、`homepage.sections`
+- 集成能力：`analytics`、`comments`、`feed`、`i18n`
+
+如果你部署到 nginx，可直接从 `nginx.conf.example` 开始调整。
+
+## 静态导出路由规则
+
+Amytis 基于 Next.js 静态导出，核心约束是 `output: "export"` 和 `trailingSlash: true`。
+
+- 在 `generateStaticParams()` 中返回原始路径片段，不要手动用 `encodeURIComponent`
+- 链接必须指向真实路径，例如 `/posts/中文测试文章`，不要写 `/posts/[slug]`
+- 文章默认路径是 `/<posts.basePath>/<slug>`，其中 `posts.basePath` 默认值为 `/posts`
+- 启用 `series.autoPaths` 后，系列文章会切换到 `/<series-slug>/<post-slug>`
+- 配置了 `series.customPaths` 时，会优先使用自定义前缀覆盖 `autoPaths`
+- 如果准备把系列文章从默认 `/posts/...` 路径迁走，先执行 `bun run add-series-redirects --dry-run`，确认后再执行 `bun run add-series-redirects`
 
 ## 内容写作
 
-- **Posts**：创建到 `content/posts/`
-- **Flows**：创建到 `content/flows/YYYY/MM/DD.mdx`（或文件夹模式）
-- **Series**：创建 `content/series/<slug>/index.mdx`
-- **Books**：创建到 `content/books/<slug>/`
-- **Notes**：创建到 `content/notes/`，支持 `[[wiki-links]]`
+- **Posts**：写入 `content/posts/`，支持单文件、日期前缀和文件夹模式。文件夹模式可将图片放在同目录的 `images/` 中。CLI：`bun run new "Post Title"` 或 `bun run new "Post Title" --folder`
+- **Flows**：写入 `content/flows/YYYY/MM/DD.md` 或 `.mdx`。CLI：`bun run new-flow`
+- **Series**：创建 `content/series/<slug>/index.mdx`，系列内文章可作为同级文件或子目录。CLI：`bun run new-series "Series Name"`
+- **Books**：写入 `content/books/<slug>/`，通常用 `index.mdx` 存元数据，其余章节文件与其并列
+- **Notes**：写入 `content/notes/`，支持 `[[wiki-links]]`。CLI：`bun run new-note "Concept"`
+- **Unicode slug**：文章和笔记支持有意使用 Unicode slug，修改动态路由时要一起验证 ASCII 和 Unicode 路径
 
 ## 项目结构
 
@@ -173,11 +199,15 @@ amytis/
     books/
     notes/
     flows/
+  docs/
+  imports/
   public/
+  scripts/
   src/
     app/
     components/
     lib/
+  tests/
   packages/
     create-amytis/
   site.config.ts

package/bun.lock

@@ -34,6 +34,7 @@
         "zod": "^4.3.6",
       },
       "devDependencies": {
+        "@playwright/test": "^1.58.2",
         "@tailwindcss/postcss": "^4.1.18",
         "@types/bun": "^1.3.9",
         "@types/d3": "^7.4.3",
@@ -286,6 +287,8 @@
 
     "@pagefind/windows-x64": ["@pagefind/windows-x64@1.4.0", "", { "os": "win32", "cpu": "x64" }, "sha512-NkT+YAdgS2FPCn8mIA9bQhiBs+xmniMGq1LFPDhcFn0+2yIUEiIG06t7bsZlhdjknEQRTSdT7YitP6fC5qwP0g=="],
 
+    "@playwright/test": ["@playwright/test@1.58.2", "", { "dependencies": { "playwright": "1.58.2" }, "bin": { "playwright": "cli.js" } }, "sha512-akea+6bHYBBfA9uQqSYmlJXn61cTa+jbO87xVLCWbTqbWadRVmhxlXATaOjOgcBaWU4ePo0wB41KMFv3o35IXA=="],
+
     "@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=="],
@@ -792,6 +795,8 @@
 
     "format": ["format@0.2.2", "", {}, "sha512-wzsgA6WOq+09wrU1tsJ09udeR/YZRaeArL9e1wPbFg3GG2yDnC2ldKpxs4xunpFF9DgqCqOIra3bc1HWrJ37Ww=="],
 
+    "fsevents": ["fsevents@2.3.2", "", { "os": "darwin" }, "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="],
+
     "function-bind": ["function-bind@1.1.2", "", {}, "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA=="],
 
     "function.prototype.name": ["function.prototype.name@1.1.8", "", { "dependencies": { "call-bind": "^1.0.8", "call-bound": "^1.0.3", "define-properties": "^1.2.1", "functions-have-names": "^1.2.3", "hasown": "^2.0.2", "is-callable": "^1.2.7" } }, "sha512-e5iwyodOHhbMr/yNrc7fDYG4qlbIvI5gajyzPnb5TCwyhjApznQh1BMFou9b30SevY43gCJKXycoCBjMbsuW0Q=="],
@@ -1232,6 +1237,10 @@
 
     "pkg-types": ["pkg-types@1.3.1", "", { "dependencies": { "confbox": "^0.1.8", "mlly": "^1.7.4", "pathe": "^2.0.1" } }, "sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ=="],
 
+    "playwright": ["playwright@1.58.2", "", { "dependencies": { "playwright-core": "1.58.2" }, "optionalDependencies": { "fsevents": "2.3.2" }, "bin": { "playwright": "cli.js" } }, "sha512-vA30H8Nvkq/cPBnNw4Q8TWz1EJyqgpuinBcHET0YVJVFldr8JDNiU9LaWAE1KqSkRYazuaBhTpB5ZzShOezQ6A=="],
+
+    "playwright-core": ["playwright-core@1.58.2", "", { "bin": { "playwright-core": "cli.js" } }, "sha512-yZkEtftgwS8CsfYo7nm0KE8jsvm6i/PTgVtB8DL726wNf6H2IMsDuxCpJj59KDaxCtSnrWan2AeDqM7JBaultg=="],
+
     "points-on-curve": ["points-on-curve@0.2.0", "", {}, "sha512-0mYKnYYe9ZcqMCWhUjItv/oHjvgEsfKvnUTg8sAtnHr3GVy7rGkXCb6d5cSyqrWqL4k81b9CPg3urd+T7aop3A=="],
 
     "points-on-path": ["points-on-path@0.2.1", "", { "dependencies": { "path-data-parser": "0.1.0", "points-on-curve": "0.2.0" } }, "sha512-25ClnWWuw7JbWZcgqY/gJ4FQWadKxGWk+3kR/7kD0tCaDtPPMj7oHu2ToLaVhfpnHrZzYby2w6tUA0eOIuUg8g=="],

package/content/posts/2026-01-12-the-art-of-algorithms.mdx

@@ -5,6 +5,9 @@ excerpt: "Implementing and visualizing the QuickSort algorithm."
 category: "Computer Science"
 tags: ["algorithms", "sorting", "typescript"]
 authors: ["Algo Master", "Math Wizard"]
+redirectFrom:
+  - /this-is-a-test-redirect-for-the-art-of-algorithms
+  - /this/is-a-test-redirect-for-the-art-of-algorithms
 ---
 
 Sorting is a fundamental concept in computer science. Let's look at **QuickSort**.

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

@@ -142,9 +142,9 @@ sequenceDiagram
 
 ![Galaxy](/images/galaxy.jpg)
 
-### Vibrant Waves (AVIF format)
+### Vibrant Waves (JPG format)
 
-![Vibrant Waves](/images/vibrant-waves.avif)
+![Vibrant Waves](/images/vibrant-waves.jpg)
 
 ### Side by Side (Raw HTML)
 

package/content/posts/multimedia-showcase/index.mdx

@@ -20,8 +20,7 @@ Responsive 16:9 YouTube embed using a padded wrapper:
   <iframe
     src="https://www.youtube.com/embed/jNQXAC9IVRw?rel=0"
     style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
-    allowfullscreen
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture; web-share"
     title="Me at the zoo — first YouTube video ever uploaded (2005)"
   ></iframe>
 </div>
@@ -39,7 +38,6 @@ Vimeo also supports responsive 16:9 embedding:
     src="https://player.vimeo.com/video/76979871?color=ff9933&title=0&byline=0&portrait=0"
     style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;"
     allow="autoplay; fullscreen; picture-in-picture"
-    allowfullscreen
     title="Big Buck Bunny — Blender Foundation (Vimeo)"
   ></iframe>
 </div>
@@ -114,8 +112,7 @@ Below is NASA's public live stream:
   <iframe
     src="https://www.youtube.com/embed/xAieE-QtOeM?autoplay=0"
     style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border: 0;"
-    allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
-    allowfullscreen
+    allow="accelerometer; autoplay; clipboard-write; encrypted-media; fullscreen; gyroscope; picture-in-picture"
     title="NASA TV Live"
   ></iframe>
 </div>
@@ -130,7 +127,7 @@ Twitch requires your site's hostname in the `parent` query parameter (so the emb
   src="https://player.twitch.tv/?channel=CHANNEL_NAME&parent=your-domain.com"
   height="378"
   width="100%"
-  allowfullscreen
+  allow="fullscreen"
   title="Twitch Stream"
 ></iframe>
 ```
@@ -249,6 +246,7 @@ When embedding third-party media, keep these in mind:
 - **`loading="lazy"`**: Add this to below-the-fold embeds to defer loading and improve page speed.
 - **`title` attribute**: Always provide a descriptive `title` for screen reader accessibility.
 - **Privacy-enhanced mode**: YouTube supports `youtube-nocookie.com` to reduce tracking when embeds don't auto-play.
+- **`allow` over `allowfullscreen`**: Use `allow="fullscreen"` instead of the deprecated `allowfullscreen` boolean attribute. Note that bare `allow="fullscreen"` restricts fullscreen to the iframe's own origin (more secure), whereas the legacy `allowfullscreen` was equivalent to `allow="fullscreen *"` (any origin). For third-party embeds like YouTube or Vimeo, `allow="fullscreen"` is the correct and preferred form. When both attributes are present the browser warns that `allow` takes precedence.
 - **`sandbox` attribute**: Use for untrusted embeds to restrict what the iframe can do.
 - **Twitch `parent` parameter**: Twitch requires your site's hostname in `parent` for embeds to work outside localhost.
 

package/content/series/markdown-showcase/syntax-highlighting.mdx

@@ -4,7 +4,7 @@ date: "2026-02-15"
 category: "Engineering"
 tags: ["code", "typescript"]
 featured: true
-coverImage: "/images/vibrant-waves.avif"
+coverImage: "/images/vibrant-waves.jpg"
 ---
 
 Amytis provides beautiful syntax highlighting for dozens of programming languages. Here are a few examples within the series context.

package/content/series/modern-web-dev/index.mdx

@@ -0,0 +1,13 @@
+---
+type: collection
+title: "Modern Web Development"
+excerpt: "A curated path through modern web development: JavaScript fundamentals, React patterns, and deep Next.js mastery."
+date: "2026-03-01"
+featured: true
+items:
+  - post: asynchronous-javascript
+  - post: understanding-react-hooks
+  - series: nextjs-deep-dive
+---
+
+This collection assembles the essential reading for anyone building modern web applications. Start with the JavaScript fundamentals that underpin everything, move into React patterns, then go deep on Next.js.

package/content/series/nextjs-deep-dive/01-getting-started.mdx

@@ -3,7 +3,7 @@ title: "Part 1: Getting Started with Next.js 15"
 date: "2026-01-30"
 excerpt: "Setting up the environment and understanding the core philosophy."
 featured: true
-coverImage: "/images/vibrant-waves.avif"
+coverImage: "/images/vibrant-waves.jpg"
 ---
 
 # Getting Started

package/docs/ARCHITECTURE.md

@@ -70,8 +70,11 @@ src/app/
 - `next.config.ts` sets `output: "export"` and `trailingSlash: true`.
 - Post URLs use `getPostUrl()` in `src/lib/urls.ts`:
   - Default: `/<posts.basePath>/<post.slug>` (basePath defaults to `posts`)
+  - Series auto path: `/<series.slug>/<post.slug>` when `series.autoPaths` is enabled
   - Series override: `/<series.customPaths[seriesSlug]>/<post.slug>`
 - Dynamic route params should return raw segment values from `generateStaticParams()` (do not pre-encode values).
+- Links should always target concrete paths, not route placeholders such as `/posts/[slug]`.
+- When moving series posts off the default posts path, `scripts/add-series-redirects.ts` updates frontmatter `redirectFrom` entries so static redirect pages can be generated.
 
 ## Key Components
 

package/docs/CONTRIBUTING.md

@@ -95,9 +95,38 @@ 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 test:mobile        # Run Playwright mobile compatibility tests
 bun run validate           # Lint + test + build:dev
 ```
 
+### Mobile Compatibility Tests
+
+`bun run test:mobile` uses [Playwright](https://playwright.dev/) to test the site across 17 real-device profiles:
+
+- **Apple:** iPhone SE, iPhone 14 Pro, iPhone 14 Pro Max, iPad Mini, iPad Pro 11
+- **Google:** Pixel 5, Pixel 7
+- **Samsung:** Galaxy S8, Galaxy S21
+- **Huawei:** P50 Pro, Mate 60
+- **Xiaomi:** Xiaomi 14, Redmi Note 13
+- **Oppo:** Find X7, Reno 11
+- **Vivo:** X100, Y100
+
+**First-time setup** — install the browser binaries once:
+
+```bash
+bunx playwright install chromium webkit
+```
+
+The test server starts automatically (`bun dev`) if one is not already running. Useful commands:
+
+```bash
+bunx playwright test --project="iPhone SE"          # Run one device
+bunx playwright test --project="iPhone SE" --headed # Headed (visible) browser
+bunx playwright show-report                         # Open HTML report
+```
+
+Tests cover: no horizontal overflow, navigation (hamburger on phones, desktop nav on tablets), mobile menu open/close, touch target sizing (≥44px), post sidebar visibility, scroll lock, font sizes, and image overflow.
+
 ## Building
 
 ```bash

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,31 @@
+# Troubleshooting
+
+## False-positive Chrome console warnings in dev mode
+
+**Related issue:** [#33](https://github.com/hutusi/amytis/issues/33)
+
+When running `bun dev` and opening the site in Chrome with certain browser extensions installed, you may see two console messages that look like project bugs:
+
+- **Error**: `Content Security Policy of your site blocks the use of eval in JavaScript.`
+- **Warning**: `Deprecated feature used; the Shared Storage API is deprecated and will be removed in a future release.`
+
+**These are not bugs in the project.** Investigation confirmed:
+
+- The dev server sends no `Content-Security-Policy` header
+- No meta CSP tag exists in the generated HTML
+- No `eval()` or `new Function()` calls exist in the compiled JS chunks
+- No `sharedStorage` references exist anywhere in the project or its dependencies
+
+The messages come from **browser extensions** (e.g. uBlock Origin, Privacy Badger) that inject their own CSP headers or access the Shared Storage API internally. Chrome attributes these to "your site" even though the project is not the source.
+
+**To verify:** Open `http://localhost:3000` in a Chrome Incognito window with extensions disabled — both messages will be gone.
+
+## AVIF source images cause 404s in production
+
+**Related upstream issue:** [Niels-IO/next-image-export-optimizer#263](https://github.com/Niels-IO/next-image-export-optimizer/issues/263)
+
+`next-image-export-optimizer` has a bug with AVIF source files when `storePicturesInWEBP=true`. The optimizer writes `.WEBP` output to disk but `ExportedImage` generates `srcset` paths with the original `.AVIF` extension — pointing to files that do not exist, causing 404 errors in production.
+
+**Workaround:** Do not use `.avif` as a source format for cover images or any image referenced via `ExportedImage`. Use `.jpg`, `.png`, or `.webp` instead — the optimizer converts these to WebP correctly.
+
+AVIF is a great format in general, but this project's static-export image pipeline (`next-image-export-optimizer`) does not handle AVIF source files correctly until the upstream bug is fixed.

package/next.config.ts

@@ -3,8 +3,14 @@ import type { NextConfig } from "next";
 const nextConfig: NextConfig = {
   /* config options here */
   reactCompiler: true,
-  // Set to true so pages export as slug/index.html, which coexists with
-  // asset directories (slug/images/) and avoids 403 errors on trailing slash
+  // Next.js default is false (slug.html), but we use true (slug/index.html)
+  // for two reasons:
+  //   1. Co-located assets: posts can have a slug/images/ directory alongside
+  //      slug/index.html. With false, slug.html and slug/ conflict on some
+  //      static hosts and cause 403 errors.
+  //   2. Nginx cosmetics: nginx.conf strips the trailing slash via redirect
+  //      (/slug/ → /slug) so the visible URL matches the false convention
+  //      without changing the export format.
   trailingSlash: true,
   output: "export",
   images: {