# Documentation

Reference for buxx.me.

## Start

What this site is, how it is put together, and how to run it.

- [Overview](https://buxx.me/docs/overview/index.md): What buxx.me is, the surfaces it exposes, and where each one is documented.
- [Architecture](https://buxx.me/docs/architecture/index.md): Runtime shape, directory layout, data sources, endpoints, cache policy, and environment variables.
- [Local development](https://buxx.me/docs/development/index.md): Getting the site running: toolchain, commands, the dev-versus-production runtime gap, and environment variables.

## Writing

Composing a post: the directive grammar, every directive, and tags.

- [How a post is built](https://buxx.me/docs/writing/overview/index.md): The path from a Ghost draft to rendered HTML, and the four things that happen to your markup on the way.
- [Directive syntax](https://buxx.me/docs/writing/directives/index.md): The [!name key=value] grammar — how markers are matched, how attributes parse, and the three kinds of directive.
- [Poems](https://buxx.me/docs/writing/poem/index.md): Verse blocks — the [!poem] marker, the two modifiers, stanza and attribution handling, and the three ways a blockquote becomes a poem on its own.
- [Listening card](https://buxx.me/docs/writing/music/index.md): The [!music] directive — an Apple Music track rendered as a playable vinyl card, and what it falls back to everywhere else.
- [Mood embeds](https://buxx.me/docs/writing/mood/index.md): The [!mood] directive and the [mood:id] shorthand — quoting a post from the short-form feed inside an essay.
- [YouTube](https://buxx.me/docs/writing/youtube/index.md): The [!youtube] directive — a click-to-load facade that keeps YouTube's scripts off the page until a reader asks for the video.
- [Conversation blocks](https://buxx.me/docs/writing/conversation/index.md): The conversation fence grammar, speaker declarations, bubble boundaries, inline markup, avatars, and layout behavior.
- [Footnotes](https://buxx.me/docs/writing/footnotes/index.md): The [^label] syntax — references, definitions, repeat references, backlinks, and the four warnings that catch a broken pair.
- [Authorship credits](https://buxx.me/docs/writing/authors/index.md): The [!authors] directive — crediting a model as a co-author, and the human-authorship pledge it replaces.
- [Tags](https://buxx.me/docs/writing/tags/index.md): Public tags, the archive routes they generate, English labels for a Chinese blog, and the internal tags that change how a post renders.
- [Publishing](https://buxx.me/docs/writing/publishing/index.md): How a post gets from a Ghost draft to a deployed page, and what breaks when it doesn't.
- [Images & code](https://buxx.me/docs/writing/media/index.md): What happens to an image and a code block between the Ghost editor and the page — blur-up placeholders, responsive sources, and syntax highlighting.

## API

Every HTTP route on buxx.me — public, gated, and internal.

- [API Overview](https://buxx.me/docs/api/overview/index.md): Who serves buxx.me/api, how versions and auth work, and the response conventions every endpoint on this site follows — or doesn't.
- [Mood API](https://buxx.me/docs/api/mood/index.md): The mood feed, detail, comments, search, stats, and live-counts endpoints — every parameter, cache tier, and error code, read straight from site-api.
- [Listening API](https://buxx.me/docs/api/listening/index.md): The now-playing track behind the home page — how the Last.fm read is cached, why a response can be real or a hardcoded demo, and how playback events are reported back.
- [Status & Edge](https://buxx.me/docs/api/status/index.md): Liveness checks, the footer status pill, and the per-visitor edge facts — four small endpoints that never cache and never fail loudly.
- [Content & Integrations](https://buxx.me/docs/api/content/index.md): Blog metadata, mood comments by post id, GitHub contributions, the MusicKit developer token, and the posts endpoint that is not switched on yet.
- [Notify API](https://buxx.me/docs/api/notify/index.md): Subscribe, confirm, unsubscribe, and manage a mood-update email subscription — the Turnstile gate, the token-in-URL auth model, and which routes return HTML instead of JSON.
- [Feeds & Machine Output](https://buxx.me/docs/api/feeds/index.md): RSS, llms.txt, sitemaps, and Markdown content negotiation for anything reading the site programmatically.
- [oEmbed & Embeds](https://buxx.me/docs/api/oembed/index.md): Embed mood posts on any page — the oEmbed protocol, the raw iframe widget, and the postMessage contract.
- [SVG Endpoints](https://buxx.me/docs/api/svg/index.md): Server-rendered badges and cards for GitHub READMEs and anywhere else that only accepts a static image.
- [Analytics API](https://buxx.me/docs/api/analytics/index.md): Seven routes that split cleanly in two — same-origin write endpoints the site's own pages call, and Cloudflare Access-gated read endpoints only the admin portal can reach.
- [Site Worker Routes](https://buxx.me/docs/api/site-routes/index.md): The endpoints the public site Worker answers itself — the media proxy, the API forwarders, the registry, and the static JSON the front end fetches.
- [Internal Endpoints](https://buxx.me/docs/api/internal/index.md): The admin, webhook, and cron-triggered routes — what exists at each path, how it is gated, and why this page lists them instead of specifying them.

## Surfaces

The pages themselves and the design rules each one follows.

- [Home page](https://buxx.me/docs/surfaces/home/index.md): Every section on the landing page, the reveal choreography, and the fixtures the tests drive it with.
- [Blog design system](https://buxx.me/docs/surfaces/blog/index.md): The ink-wash design language of 無人之境 — one blue hue, foreground-derived greys, and a single reading column.
- [Mood](https://buxx.me/docs/surfaces/mood/index.md): The three-level mood surface: home preview, feed wheel, and detail page.
- [Shared layout](https://buxx.me/docs/surfaces/layout/index.md): Chrome that every page inherits: the layout shell, theme switch, command palette, and footer.
- [Spotlight overlay](https://buxx.me/docs/surfaces/spotlight/index.md): The pointer-tracking spotlight over the dot grid, and why it is one fixed layer.
- [Mascot](https://buxx.me/docs/surfaces/mascot/index.md): peek, the site mascot: where the sprites live, how it is placed, and what it must never do.
- [Component register](https://buxx.me/docs/surfaces/components/index.md): How /components is assembled, and how a piece is published to the shadcn registry at /r.

## Platform

Workers, ingestion, delivery, auth, and what the tests cover.

- [Worker and site](https://buxx.me/docs/platform/worker/index.md): The public Cloudflare Worker: routing, the API fallback binding, and static asset delivery.
- [Telegram pipeline](https://buxx.me/docs/platform/telegram/index.md): How a Telegram post becomes a mood: ingestion, HD images, and the archive mirror.
- [Email notifications](https://buxx.me/docs/platform/notify/index.md): The Resend-backed notify runtime, its queues, and the admin surface that drives it.
- [Auth and OAuth hub](https://buxx.me/docs/platform/auth/index.md): The owner-auth boundary, the GitHub admin session, and the credential roadmap.
- [Security](https://buxx.me/docs/platform/security/index.md): Headers, rate limits, Turnstile, embed isolation, and the static asset guard.
- [SEO and metadata](https://buxx.me/docs/platform/seo/index.md): Public identity strings, structured data, sitemaps, and per-page metadata.
- [Test coverage](https://buxx.me/docs/platform/testing/index.md): The behavior surface the Playwright suite covers, and what it deliberately does not.
- [Privacy policy](https://buxx.me/docs/platform/privacy/index.md): How the published privacy page maps onto what the site actually collects.