@hutusi/amytis 1.9.0 → 1.11.0

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/books/sample-book/images/digital-garden.svg

@@ -0,0 +1,25 @@
+<svg width="800" height="400" xmlns="http://www.w3.org/2000/svg">
+  <rect width="800" height="400" rx="12" fill="#f0fdf4"/>
+  <rect x="1" y="1" width="798" height="398" rx="12" fill="none" stroke="#86efac" stroke-width="2"/>
+
+  <!-- Decorative circles -->
+  <circle cx="120" cy="200" r="60" fill="#bbf7d0" opacity="0.6"/>
+  <circle cx="680" cy="200" r="60" fill="#bbf7d0" opacity="0.6"/>
+  <circle cx="400" cy="100" r="40" fill="#86efac" opacity="0.4"/>
+
+  <!-- Simple tree/plant shapes -->
+  <polygon points="120,220 95,270 145,270" fill="#4ade80"/>
+  <rect x="113" y="268" width="14" height="20" fill="#166534"/>
+  <polygon points="120,190 90,240 150,240" fill="#22c55e"/>
+
+  <polygon points="680,220 655,270 705,270" fill="#4ade80"/>
+  <rect x="673" y="268" width="14" height="20" fill="#166534"/>
+  <polygon points="680,190 650,240 710,240" fill="#22c55e"/>
+
+  <!-- Title text -->
+  <text x="400" y="175" text-anchor="middle" font-family="Georgia, serif" font-size="42" font-weight="bold" fill="#14532d">The Digital Garden</text>
+  <text x="400" y="225" text-anchor="middle" font-family="Georgia, serif" font-size="22" font-style="italic" fill="#166534">A place for ideas to grow</text>
+
+  <!-- Subtitle -->
+  <text x="400" y="310" text-anchor="middle" font-family="Arial, sans-serif" font-size="16" fill="#4ade80">✦ cultivate · connect · contribute ✦</text>
+</svg>

package/content/books/sample-book/index.mdx

@@ -2,7 +2,7 @@
 title: "The Digital Garden Handbook"
 excerpt: "A comprehensive guide to building and maintaining your own digital garden, from initial setup to advanced techniques."
 date: "2026-01-15"
-coverImage: "text:DG"
+coverImage: "/images/flowers.jpg"
 featured: true
 draft: false
 authors: ["Amytis"]

package/content/books/sample-book/introduction.mdx

@@ -3,6 +3,8 @@ title: "Introduction to Digital Gardens"
 excerpt: "Understanding the philosophy and history behind digital gardens."
 ---
 
+![The Digital Garden](./images/digital-garden.svg)
+
 ## What is a Digital Garden?
 
 A digital garden is a personal online space where ideas are cultivated over time. Unlike a traditional blog with polished, finished posts, a digital garden embraces the concept of learning in public.

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/content/posts/legacy-markdown.md

@@ -5,8 +5,6 @@ excerpt: "Demonstrating support for standard .md files."
 category: "Meta"
 tags: ["markdown", "legacy"]
 author: "Old Timer"
-featured: true
-coverImage: "text:Legacy Markdown"
 ---
 
 # Legacy Markdown Support

package/content/posts/markdown-features.mdx

@@ -5,8 +5,8 @@ excerpt: "Testing tables, task lists, and other GFM features."
 category: "Test"
 tags: ["markdown", "gfm"]
 author: "Tester"
-coverImage: "text:Markdown"
 featured: true
+coverImage: "/images/cappadocia.jpg"
 ---
 
 # Extended Markdown Features

package/content/posts/multilingual-test.mdx

@@ -6,7 +6,6 @@ category: "测试"
 tags: ["chinese", "multilingual", "test"]
 authors: ["Amytis Team"]
 latex: true
-featured: true
 coverImage: "text:Multilingual"
 ---
 

package/content/posts/syntax-highlighting-showcase.mdx

@@ -6,6 +6,7 @@ category: "Showcase"
 tags: ["test", "code", "syntax-highlighting"]
 authors: ["Amytis Team"]
 featured: true
+coverImage: "/images/antelope-canyon.jpg"
 toc: true
 externalLinks:
   - name: "Prism.js"

package/content/posts/understanding-react-hooks.mdx

@@ -6,6 +6,7 @@ category: "Engineering"
 tags: ["react", "hooks", "frontend"]
 author: "Code Gardener"
 featured: true
+coverImage: "/images/antelope-canyon.jpg"
 ---
 
 React Hooks revolutionized how we write components. Let's explore the core hooks.

package/content/series/ai-nexus-weekly/index.mdx

@@ -2,7 +2,7 @@
 title: "AI Nexus Weekly"
 excerpt: "A curated weekly digest exploring the rapidly evolving landscape of Artificial Intelligence, from large language models to robotics."
 date: "2026-02-17"
-coverImage: "text:AI Nexus"
+coverImage: "/images/galaxy.jpg"
 featured: true
 sort: "date-desc"
 ---

package/content/series/digital-garden/01-philosophy.mdx

@@ -5,6 +5,8 @@ excerpt: "How ideas evolve from raw daily flows into articles, series, and books
 category: "Philosophy"
 tags: ["pkm", "knowledge management", "learning"]
 authors: ["Amytis Team"]
+featured: true
+coverImage: "/images/mountains.jpg"
 ---
 
 # The Philosophy of Digital Gardening

package/content/series/digital-garden/index.mdx

@@ -2,7 +2,7 @@
 title: "The Digital Garden"
 excerpt: "Exploring the philosophy and architecture of modern digital gardens. A journey from linear blogs to non-linear knowledge systems."
 date: "2026-02-11"
-coverImage: "text:Digital Garden"
+coverImage: "/images/mountains.jpg"
 featured: true
 sort: "manual"
 posts: ["01-philosophy", "02-architecture"]

package/content/series/markdown-showcase/index.mdx

@@ -2,7 +2,7 @@
 title: "Markdown Showcase"
 excerpt: "A comprehensive tour of the rich content features supported by Amytis, from Mermaid diagrams to LaTeX math."
 date: "2026-02-13"
-coverImage: "text:MDX Showcase"
+coverImage: "/images/lake.jpg"
 featured: true
 sort: "manual"
 posts: ["visuals-and-diagrams", "mathematical-notation", "syntax-highlighting"]

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

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

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

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

package/content/series/nextjs-deep-dive/index.mdx

@@ -2,8 +2,8 @@
 title: "Next.js Deep Dive"
 excerpt: "A comprehensive guide to mastering Next.js 15, including advanced routing, data fetching, and performance optimization."
 date: "2026-01-30"
-coverImage: "https://images.unsplash.com/photo-1618005182384-a83a8bd57fbe?auto=format&fit=crop&w=800&q=80"
 sort: "manual"
+coverImage: "/images/cappadocia.jpg"
 posts:
   - "01-getting-started"
   - "02-routing-mastery"

package/content/subscribe.mdx

@@ -0,0 +1,27 @@
+---
+title: "Subscribe"
+excerpt: "Stay updated with new posts and notes."
+---
+
+Choose how you'd like to follow along.
+
+## RSS Feed
+
+RSS is an open standard — no account required. Paste the feed URL into any reader app, or use one of the quick-subscribe links below.
+
+<rss-feed></rss-feed>
+
+**Popular readers:** [Follow](https://app.follow.is) · [Feedly](https://feedly.com) · [Inoreader](https://www.inoreader.com) · [NetNewsWire](https://netnewswire.com) · [NewsBlur](https://newsblur.com)
+
+## Newsletter
+
+Subscribe via email to get new posts delivered to your inbox.
+
+[Subscribe →](https://example.com)
+
+## Social
+
+Follow for updates and discussions.
+
+- [X (Twitter)](https://twitter.com)
+- [GitHub](https://github.com)

package/docs/ARCHITECTURE.md

@@ -1,120 +1,100 @@
 # Architecture Overview
 
-Amytis is a static site generator built with **Next.js 16 (App Router)**, designed to render a "digital garden" of Markdown/MDX content.
+Amytis is a static-export-first Next.js 16 App Router project for Markdown/MDX publishing across posts, series, books, flows, and notes.
 
 ## Core Stack
 
-- **Framework:** Next.js 16.1.6 (App Router) with React 19
-- **Runtime:** Bun
-- **Styling:** Tailwind CSS v4 with CSS variables for theming
-- **Content:** Local `.md`/`.mdx` files parsed at build time
-- **Validation:** Zod for frontmatter schema validation
-- **Testing:** Bun Test
+- Framework: Next.js 16.1.6 + React 19
+- Runtime/tooling: Bun
+- Styling: Tailwind CSS v4 + CSS variables + `next-themes`
+- Content parsing: `gray-matter` + Zod validation in `src/lib/markdown.ts`
+- Search: Pagefind (`/pagefind/pagefind.js` loaded at runtime)
+- Tests: Bun test suites in `src/` and `tests/`
 
-## Data Flow
+## Content Model
 
-1. **Source:** Content lives in `content/posts/`, `content/series/`, `content/books/`, and `content/flows/`.
-2. **Parsing:** `src/lib/markdown.ts` reads the file system using Node.js `fs`. It uses `gray-matter` to parse frontmatter, `zod` to validate the schema, and `image-size` to extract image dimensions.
-3. **Filtering:** Draft content (`draft: true`) is excluded in production. Future-dated posts are hidden unless `showFuturePosts` is enabled.
-4. **Rendering:**
-   - **Lists:** `getAllPosts()` / `getAllBooks()` / `getAllFlows()` returns sorted metadata for listing pages.
-   - **Single Post/Book:** `getPostBySlug(slug)` / `getBookData(slug)` reads a specific file with full content.
-   - **Series:** `getSeriesPosts(slug)` fetches posts for a series.
-   - **Book Chapters:** `getBookChapter(bookSlug, chapterSlug)` fetches individual chapter content.
-   - **Flows:** `getFlowBySlug(slug)` fetches individual flow entries.
-   - **Static Generation:** `generateStaticParams` is implemented in dynamic routes (`[slug]`, `[page]`, `[tag]`, `[author]`, `[year]`) to pre-render all pages at build time.
+- `content/posts/`: standalone posts (`.md/.mdx`) and folder posts (`index.mdx`)
+- `content/series/<slug>/`: series metadata (`index.mdx`) + series posts
+- `content/books/<slug>/`: book metadata + chapter files
+- `content/flows/YYYY/MM/DD.(md|mdx)`: daily flow entries
+- `content/notes/`: evergreen notes
+- `content/*.mdx`: static pages (about, links, subscribe, privacy, etc.)
 
-## Route Structure
+## Runtime Data Flow
 
-```
+1. Source files are read from disk by `src/lib/markdown.ts`.
+2. Frontmatter is parsed and validated (invalid frontmatter throws at build time).
+3. Draft/future filtering and sorting are applied (based on `site.config.ts`).
+4. Route files consume typed helpers (`getAllPosts`, `getBookData`, `getAllFlows`, `getAllNotes`, etc.).
+5. `generateStaticParams()` precomputes dynamic routes for static export.
+
+## Route Map (App Router)
+
+```text
 src/app/
-  page.tsx                          # Homepage (hero, featured, latest)
-  layout.tsx                        # Root layout (providers, navbar, footer)
-  posts/
-    [slug]/page.tsx                 # Individual post
-    page.tsx                        # Posts listing
-  series/
-    page.tsx                        # All series overview
-    [slug]/page.tsx                 # Single series
-  books/
-    page.tsx                        # All books overview
-    [slug]/page.tsx                 # Book landing page
-    [slug]/[chapter]/page.tsx       # Individual book chapter
-  notes/
-    page.tsx                        # All notes list
-    [slug]/page.tsx                 # Individual note
-  graph/
-    page.tsx                        # Knowledge graph visualization
-  flows/
-    page.tsx                        # Flows stream/listing
-    [year]/[month]/[day]/page.tsx   # Individual flow entry (optional if modal/stream used)
-  tags/
-    page.tsx                        # Tag cloud
-    [tag]/page.tsx                  # Posts by tag
-  authors/
-    [author]/page.tsx               # Posts by author
-  archive/
-    page.tsx                        # Chronological archive
-  subscribe/
-    page.tsx                        # Subscription options
-  search.json/
-    route.ts                        # Supplementary structured search data
-  [slug]/page.tsx                   # Static pages (about, etc.)
+  page.tsx                          # Homepage
+  page/[page]/page.tsx              # Homepage pagination
+  layout.tsx                        # Root layout/providers
+  posts/page.tsx                    # Posts index
+  posts/page/[page]/page.tsx        # Posts pagination
+  posts/[slug]/page.tsx             # Canonical post route
+  series/page.tsx                   # Series index
+  series/[slug]/page.tsx            # Series detail
+  series/[slug]/page/[page]/page.tsx
+  books/page.tsx                    # Books index
+  books/[slug]/page.tsx             # Book landing
+  books/[slug]/[chapter]/page.tsx   # Book chapter
+  flows/page.tsx                    # Flow index
+  flows/page/[page]/page.tsx        # Flow pagination
+  flows/[year]/page.tsx
+  flows/[year]/[month]/page.tsx
+  flows/[year]/[month]/[day]/page.tsx
+  notes/page.tsx                    # Notes index
+  notes/page/[page]/page.tsx
+  notes/[slug]/page.tsx
+  tags/page.tsx
+  tags/[tag]/page.tsx
+  authors/[author]/page.tsx
+  archive/page.tsx
+  graph/page.tsx
+  feed.xml/route.ts
+  search.json/route.ts
+  sitemap.ts
+  [slug]/page.tsx                   # Static pages + custom series listing path
+  [slug]/page/[page]/page.tsx       # Custom series listing pagination
+  [slug]/[postSlug]/page.tsx        # Custom post basePath/series post path
 ```
 
-## Component Architecture
-
-### Layout Components
-- **`Navbar`** - Config-driven navigation with series dropdown, search trigger, theme toggle, and language switch.
-- **`Footer`** - Social links, copyright, site metadata, and language switch.
-- **`Hero`** - Homepage hero with collapsible intro.
-- **`BookLayout`** - Dedicated layout for book chapters with sidebar navigation.
-- **`PageHeader`** - Consistent header for simple pages (Archive, Tags, About).
-
-### Content Display
-- **`PostList`** - Card-based post listing.
-- **`FlowContent`** - Stream-based display for daily notes with timeline grouping.
-- **`SeriesCatalog`** - Timeline-style post listing for series.
-- **`PostCard`** - Individual post preview card.
-- **`CoverImage`** - Optimized image component using `next-image-export-optimizer` with dynamic desaturated gradients.
-- **`ShareBar`** - Social sharing buttons for posts and books.
-- **`TagContentTabs`** - Tabbed interface for filtering posts vs flows by tag.
-
-### Content Rendering
-- **`MarkdownRenderer`** - Core rendering component using `react-markdown` with plugins (GFM, Math, Raw HTML).
-- **`CodeBlock`** - Syntax-highlighted code blocks with copy button.
-- **`Mermaid`** - Client-side Mermaid diagram rendering.
-
-### Navigation & Discovery
-- **`TableOfContents`** - Sticky TOC with scroll-based tracking.
-- **`Search`** - Full-text search modal (Cmd/Ctrl+K) powered by Pagefind. Supports type filter tabs (All/Post/Flow/Book), recent searches, keyboard navigation, debounced input, focus trap, and ARIA accessibility. Search syntax: `"exact phrase"`, `word1 word2` (AND), `-exclude`.
-- **`Pagination`** - Previous/Next page navigation.
-- **`ReadingProgressBar`** - Top-of-page progress bar for book chapters.
-- **`SubscribePage`** - Centralized page for all subscription options.
-
-## Data Access Layer (`src/lib/markdown.ts`)
-
-| Function | Returns | Purpose |
-|----------|---------|---------|
-| `getAllPosts()` | `PostData[]` | All posts, filtered and sorted |
-| `getAllFlows()` | `FlowData[]` | All daily notes, sorted by date |
-| `getAllBooks()` | `BookData[]` | All books metadata |
-| `getBookData(slug)` | `BookData \| null` | Single book metadata & TOC |
-| `getBookChapter(...)` | `BookChapterData` | Single chapter content |
-| `getAllNotes()` | `NoteData[]` | All notes, sorted by date |
-| `getNoteBySlug(slug)` | `NoteData \| null` | Single note content |
-| `getBacklinks(slug)` | `BacklinkSource[]` | Inbound links for a page |
-| `getFlowBySlug(slug)` | `FlowData \| null` | Single flow entry |
-| `getSeriesPosts(slug)` | `PostData[]` | Posts in a series |
-| `calculateReadingTime(content)` | `string` | Estimated reading time (multilingual) |
-
-## Theming
-
-Theming is handled by `next-themes` and Tailwind CSS v4. `src/app/globals.css` defines CSS variables for palettes (`default`, `blue`, `rose`, `amber`).
+## URL Routing Rules
+
+- `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 override: `/<series.customPaths[seriesSlug]>/<post.slug>`
+- Dynamic route params should return raw segment values from `generateStaticParams()` (do not pre-encode values).
+
+## Key Components
+
+- Layout/navigation: `Navbar`, `Footer`, `Hero`, `FlowHubTabs`
+- Content renderers: `MarkdownRenderer`, `CodeBlock`, `Mermaid`
+- Post surfaces: `PostLayout`, `PostSidebar`, `PostCard`, `RelatedPosts`, `ShareBar`
+- Notes/flows discovery: `NoteSidebar`, `FlowContent`, `FlowCalendarSidebar`, `TagContentTabs`
+- Search/discovery: `Search`, `Pagination`, `KnowledgeGraph`
+
+## Data Layer Highlights (`src/lib/markdown.ts`)
+
+- Posts/series: `getAllPosts`, `getListingPosts`, `getPostBySlug`, `getSeriesPosts`, `getSeriesData`
+- Books: `getAllBooks`, `getBookData`, `getBookChapter`
+- Flows: `getAllFlows`, `getFlowBySlug`, `getFlowsByYear`, `getFlowsByMonth`
+- Notes: `getAllNotes`, `getNoteBySlug`, `getNotesByTag`
+- Discovery: `buildSlugRegistry`, `getBacklinks`, `getAllTags`, `getAllAuthors`
 
 ## Build Pipeline
 
-1. **`scripts/copy-assets.ts`** - Copies images from content directories (`posts/`, `series/`, `books/`, `flows/`) to `public/posts/` for static hosting.
-2. **`next build`** - Next.js static export to `out/`.
-3. **`next-image-export-optimizer`** - Generates optimized WebP variants (production build only).
-4. **`pagefind --site out`** - Crawls the exported HTML and builds a full-text search index in `out/pagefind/`. The index is loaded at runtime by `src/components/Search.tsx` via a dynamic import. Pure utility functions used by the search component and the search index route live in `src/lib/search-utils.ts`.
+1. `bun scripts/copy-assets.ts`: copy co-located media into `public/`
+2. `bun run build:graph`: generate graph data
+3. `next build`: static export to `out/`
+4. Production only (`bun run build`): `next-image-export-optimizer`
+5. Pagefind indexing:
+   - Production: `pagefind --site out` (writes to `out/pagefind`)
+   - Dev build: `pagefind --site out --output-path public/pagefind`

package/docs/CONTRIBUTING.md

@@ -62,9 +62,6 @@ Notes live in `content/notes/`.
 ```bash
 # Create a new note using the dedicated script
 bun run new-note "Zettelkasten Method"
-
-# Or using the general new script
-bun run new "Zettelkasten Method" --note
 ```
 
 ### Importing Content
@@ -96,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
@@ -106,6 +105,15 @@ bun run build              # Production build (includes image optimization and P
 bun run build:dev          # Development build (faster, no image optimization; also generates Pagefind index)
 ```
 
+## Static Export Routing Rules
+
+Amytis relies on static export (`output: "export"`) with `trailingSlash: true`.
+
+- In `generateStaticParams()`, return raw segment values and let Next.js handle encoding.
+- Do not pre-encode route params with `encodeURIComponent`.
+- Do not link to placeholder routes such as `/posts/[slug]`; always link to concrete URLs.
+- When touching dynamic routes, verify both ASCII and Unicode slugs.
+
 ## Code Style
 
 - **Linting:** `bun run lint`