@hutusi/amytis 1.6.0 → 1.7.0

package/GEMINI.md

@@ -43,9 +43,13 @@ bun test
   - `archive/`: Timeline-based chronological archive grouped by year and month.
   - `tags/`: Popularity-sorted tag cloud and filtered listings.
   - `authors/`: Posts filtered by individual authors.
+  - `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.
 

package/TODO.md

@@ -1,25 +1,21 @@
 # Amytis Roadmap
 
-## 🚀 Immediate UX & Polish
-- [ ] **Interactive Code**: Add "Copy to Clipboard" buttons to code blocks.
+## 🚀 Priority UX & Engineering
 - [ ] **Image Zoom**: Implement medium-zoom or a lightbox for MDX images.
-- [ ] **Breadcrumbs**: Add path navigation (e.g., `Home > Books > Chapter`) to all pages.
-- [ ] **Smart Nav**: Add "Previous" and "Next" article links at the bottom of posts.
+- [ ] **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.
-- [ ] **Recent Notes**: Integrate a "Recent Flows" section on the homepage.
-
-## 🛠 Performance & Social
-- [ ] **Dynamic OG**: Generate automated social cards with Satori based on post titles.
-- [ ] **PWA**: Add a manifest and service worker for basic offline reading support.
-- [ ] **Search UI**: Refine Pagefind results with highlighted context and better mobile layout.
+- [ ] **Knowledge Graph**: Interactive visual map of all connected notes.
 
 ## ✅ Completed Highlights
-- [x] **Full-text Search**: Migrated to **Pagefind** for high-performance static indexing.
+- [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] **Scoped Publishing**: Official release as `@hutusi/amytis` on npm and GitHub.
-- [x] **Robust Engineering**: Zero hydration mismatches, full Zod validation, and 64+ automated tests.
-- [x] **Refined UI**: High-contrast typography, four color palettes, and horizontal featured scrolling.
-- [x] **Asset Pipeline**: Automatic co-located image mapping and WebP optimization.
+- [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

@@ -16,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",
@@ -1237,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.

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

@@ -0,0 +1,261 @@
+---
+title: "Multimedia Showcase: Video, Podcasts & Embeds"
+date: "2026-02-20"
+excerpt: "A comprehensive test of multimedia embedding support — YouTube, Vimeo, podcasts, livestreams, HTML5 native media, and audio platforms."
+category: "Showcase"
+tags: ["multimedia", "video", "audio", "podcast", "embed", "test"]
+coverImage: "text:Media"
+toc: true
+---
+
+This post tests how Amytis renders multimedia content embedded via raw HTML iframes and native HTML5 media elements. Since `rehype-raw` is enabled, standard HTML embed codes work directly inside Markdown.
+
+---
+
+## YouTube Video
+
+Responsive 16:9 YouTube embed using a padded wrapper:
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 12px; margin: 1.5rem 0;">
+  <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
+    title="Me at the zoo — first YouTube video ever uploaded (2005)"
+  ></iframe>
+</div>
+
+*"Me at the zoo" — the very first video uploaded to YouTube (April 23, 2005).*
+
+---
+
+## Vimeo Video
+
+Vimeo also supports responsive 16:9 embedding:
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 12px; margin: 1.5rem 0;">
+  <iframe
+    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>
+
+*Big Buck Bunny (2008) — open-source animated short by the Blender Foundation.*
+
+---
+
+## Podcast Embeds
+
+### Spotify Podcast
+
+Spotify provides a fixed-height iframe embed for individual episodes:
+
+<iframe
+  src="https://open.spotify.com/embed/episode/0b8q6Q7fKqZLlSc0Lh1WQe?utm_source=generator&theme=0"
+  style="border-radius: 12px; margin: 1rem 0;"
+  width="100%"
+  height="152"
+  frameborder="0"
+  allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
+  loading="lazy"
+  title="Spotify Podcast Episode"
+></iframe>
+
+You can also embed the full show player at a taller height (352px) to show the episode list:
+
+<iframe
+  src="https://open.spotify.com/embed/show/5as3aKmN2k11yfDDDSrvaZ?utm_source=generator"
+  style="border-radius: 12px; margin: 1rem 0;"
+  width="100%"
+  height="352"
+  frameborder="0"
+  allow="autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture"
+  loading="lazy"
+  title="Spotify Show Player"
+></iframe>
+
+### Apple Podcasts
+
+Apple Podcasts uses a similar iframe embed pattern:
+
+<iframe
+  src="https://embed.podcasts.apple.com/us/podcast/syntax-tasty-web-development-treats/id1253186678?itsct=podcast_box_player&amp;itscg=30200&amp;ls=1&amp;theme=auto"
+  height="175px"
+  frameborder="0"
+  sandbox="allow-forms allow-popups allow-same-origin allow-scripts allow-top-navigation-by-user-activation"
+  allow="autoplay *; encrypted-media *; clipboard-write"
+  style="width: 100%; max-width: 660px; overflow: hidden; border-radius: 10px; margin: 1rem 0; display: block;"
+  title="Apple Podcasts — Syntax.fm"
+></iframe>
+
+---
+
+## Livestream Embeds
+
+### YouTube Live
+
+A YouTube Live channel or active live video can be embedded exactly like a regular video. Use the channel's live URL (`/live`) or a live event ID:
+
+```html
+<!-- Replace CHANNEL_ID with the YouTube channel ID -->
+<iframe
+  src="https://www.youtube.com/embed/live_stream?channel=CHANNEL_ID"
+  ...
+></iframe>
+```
+
+Below is NASA's public live stream:
+
+<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden; border-radius: 12px; margin: 1.5rem 0;">
+  <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
+    title="NASA TV Live"
+  ></iframe>
+</div>
+
+### Twitch Stream
+
+Twitch requires your site's hostname in the `parent` query parameter (so the embed works in production):
+
+```html
+<!-- Replace CHANNEL_NAME with a Twitch channel, and your-domain.com with your domain -->
+<iframe
+  src="https://player.twitch.tv/?channel=CHANNEL_NAME&parent=your-domain.com"
+  height="378"
+  width="100%"
+  allowfullscreen
+  title="Twitch Stream"
+></iframe>
+```
+
+Twitch also supports embedding past broadcasts (VODs) and clips:
+
+```html
+<!-- VOD -->
+<iframe src="https://player.twitch.tv/?video=VOD_ID&parent=your-domain.com" ...></iframe>
+<!-- Clip -->
+<iframe src="https://clips.twitch.tv/embed?clip=CLIP_SLUG&parent=your-domain.com" ...></iframe>
+```
+
+---
+
+## HTML5 Native Media
+
+Native `<video>` and `<audio>` elements work without any third-party embeds.
+
+### HTML5 Video
+
+<video
+  controls
+  style="width: 100%; border-radius: 12px; margin: 1rem 0; background: #000;"
+  poster="https://peach.blender.org/wp-content/uploads/title_anouncement.jpg"
+>
+  <source src="https://commondatastorage.googleapis.com/gtv-videos-bucket/sample/ElephantsDream.mp4" type="video/mp4" />
+  Your browser does not support the HTML5 video element.
+</video>
+
+*Elephants Dream (2006) — first open-source animated film by the Blender Foundation.*
+
+Attributes you can use:
+
+| Attribute | Description |
+| :--- | :--- |
+| `controls` | Show playback controls |
+| `autoplay` | Start playing automatically (use with `muted`) |
+| `muted` | Mute by default (required for autoplay) |
+| `loop` | Loop the video |
+| `poster` | Preview image shown before play |
+| `preload` | `auto` \| `metadata` \| `none` |
+
+### HTML5 Audio
+
+<audio
+  controls
+  style="width: 100%; margin: 1rem 0;"
+>
+  <source src="https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3" type="audio/mpeg" />
+  Your browser does not support the HTML5 audio element.
+</audio>
+
+*SoundHelix royalty-free sample track.*
+
+Multiple formats improve cross-browser support:
+
+```html
+<audio controls>
+  <source src="audio.ogg" type="audio/ogg" />
+  <source src="audio.mp3" type="audio/mpeg" />
+  Your browser does not support the HTML5 audio element.
+</audio>
+```
+
+---
+
+## Audio Platforms
+
+### SoundCloud
+
+SoundCloud exposes an iframe embed from any track's "Share → Embed" menu:
+
+<iframe
+  width="100%"
+  height="166"
+  scrolling="no"
+  frameborder="no"
+  allow="autoplay"
+  style="border-radius: 8px; margin: 1rem 0;"
+  src="https://w.soundcloud.com/player/?url=https%3A//api.soundcloud.com/tracks/1&color=%23ff5500&auto_play=false&hide_related=false&show_comments=true&show_user=true&show_reposts=false&show_teaser=true"
+  title="SoundCloud track"
+></iframe>
+
+The full visual player (300px height) shows the waveform:
+
+```html
+<iframe
+  width="100%"
+  height="300"
+  src="https://w.soundcloud.com/player/?url=TRACK_URL&visual=true"
+  ...
+></iframe>
+```
+
+### Bandcamp
+
+Bandcamp provides both album and track embed codes:
+
+```html
+<!-- Album embed -->
+<iframe
+  style="border: 0; width: 100%; height: 120px;"
+  src="https://bandcamp.com/EmbeddedPlayer/album=ALBUM_ID/size=large/bgcol=ffffff/linkcol=0687f5/"
+  seamless
+></iframe>
+```
+
+---
+
+## Embed Best Practices
+
+When embedding third-party media, keep these in mind:
+
+- **Responsive sizing**: Wrap iframes in a `padding-bottom: 56.25%; position: relative` container to maintain 16:9 ratio.
+- **`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.
+- **`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.
+
+```html
+<!-- YouTube privacy-enhanced embed -->
+<iframe
+  src="https://www.youtube-nocookie.com/embed/VIDEO_ID?rel=0"
+  ...
+></iframe>
+```

package/content/privacy.mdx

@@ -0,0 +1,32 @@
+---
+title: "Privacy Policy"
+date: "2026-02-20"
+excerpt: "How this site collects and handles your data."
+layout: "simple"
+---
+
+# Privacy Policy
+
+Your privacy matters. This page explains what data is collected when you visit this site and how it is used.
+
+## Analytics
+
+This site uses **Umami**, a privacy-focused, open-source analytics platform. Umami does not use cookies, does not track users across websites, and does not collect personally identifiable information. The data collected is limited to anonymous page-view statistics such as referrer, browser type, and country — used solely to understand which content is most useful.
+
+No data is sold or shared with third parties.
+
+## Comments
+
+Post comments are powered by **Giscus**, which uses GitHub Discussions. To leave a comment you must sign in with a GitHub account. Your comment and GitHub username are stored by GitHub and are subject to [GitHub's Privacy Policy](https://docs.github.com/en/site-policy/privacy-policies/github-general-privacy-statement).
+
+If you do not have a GitHub account or prefer not to use it, you can always reach out directly by email.
+
+## External Links
+
+This site may contain links to external websites. Once you leave this site, the privacy practices of those third-party sites apply and are outside this site's control.
+
+## Contact
+
+If you have any questions about this privacy policy, feel free to reach out at the email address listed in the footer.
+
+*Last updated: February 2026.*