All docs
Documentation
Everything this site does, written down.
42 pages covering how buxx.me is built: the runtime and its boundaries, the directive syntax posts are composed with, the public endpoints anyone can call, and the rules each surface follows.
Start
What this site is, how it is put together, and how to run it.
- Overview What buxx.me is, the surfaces it exposes, and where each one is documented.
- Architecture Runtime shape, directory layout, data sources, endpoints, cache policy, and environment variables.
- Local development 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 The path from a Ghost draft to rendered HTML, and the four things that happen to your markup on the way.
- Directive syntax The [!name key=value] grammar — how markers are matched, how attributes parse, and the three kinds of directive.
- Poems 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 The [!music] directive — an Apple Music track rendered as a playable vinyl card, and what it falls back to everywhere else.
- Mood embeds The [!mood] directive and the [mood:id] shorthand — quoting a post from the short-form feed inside an essay.
- YouTube 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 The conversation fence grammar, speaker declarations, bubble boundaries, inline markup, avatars, and layout behavior.
- Footnotes The [^label] syntax — references, definitions, repeat references, backlinks, and the four warnings that catch a broken pair.
- Authorship credits The [!authors] directive — crediting a model as a co-author, and the human-authorship pledge it replaces.
- Tags Public tags, the archive routes they generate, English labels for a Chinese blog, and the internal tags that change how a post renders.
- Publishing How a post gets from a Ghost draft to a deployed page, and what breaks when it doesn't.
- Images & code 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 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 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 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 Liveness checks, the footer status pill, and the per-visitor edge facts — four small endpoints that never cache and never fail loudly.
- Content & Integrations 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 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 RSS, llms.txt, sitemaps, and Markdown content negotiation for anything reading the site programmatically.
- oEmbed & Embeds Embed mood posts on any page — the oEmbed protocol, the raw iframe widget, and the postMessage contract.
- SVG Endpoints SSR Server-rendered badges and cards for GitHub READMEs and anywhere else that only accepts a static image.
- Analytics API 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 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 Gated 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 Every section on the landing page, the reveal choreography, and the fixtures the tests drive it with.
- Blog design system The ink-wash design language of 無人之境 — one blue hue, foreground-derived greys, and a single reading column.
- Mood The three-level mood surface: home preview, feed wheel, and detail page.
- Shared layout Chrome that every page inherits: the layout shell, theme switch, command palette, and footer.
- Spotlight overlay The pointer-tracking spotlight over the dot grid, and why it is one fixed layer.
- Mascot peek, the site mascot: where the sprites live, how it is placed, and what it must never do.
- Component register 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 The public Cloudflare Worker: routing, the API fallback binding, and static asset delivery.
- Telegram pipeline How a Telegram post becomes a mood: ingestion, HD images, and the archive mirror.
- Email notifications The Resend-backed notify runtime, its queues, and the admin surface that drives it.
- Auth and OAuth hub The owner-auth boundary, the GitHub admin session, and the credential roadmap.
- Security Headers, rate limits, Turnstile, embed isolation, and the static asset guard.
- SEO and metadata Public identity strings, structured data, sitemaps, and per-page metadata.
- Test coverage The behavior surface the Playwright suite covers, and what it deliberately does not.
- Privacy policy How the published privacy page maps onto what the site actually collects.