Honest essays on leadership, programming, and the messy overlap between humans and tech.
Overview • Getting started • Project structure • Writing an essay • Tooling • Automation • Deployment
The front-end source of buthonestly.io — a static Astro site built from MDX.
Essays live in src/content/essays, one folder per essay, holding an MDX source
and its images side by side. Ordinary prose uses standard Markdown; figures,
galleries, summaries, callouts, and attributed quotations use a small set of
Astro components. The shared essay inventory owns source discovery, metadata,
publication state, URLs, and reader-facing hashes. Astro's content collection
adds rendering and image metadata. There is no CMS and no database — a new essay
is a commit.
What the build gives you beyond the pages:
- Date-driven publishing. A future publication day schedules an essay; an hourly Action deploys a missing or stale public version, waits for its content hash, then independently notifies IndexNow and delivers its Kit broadcast. Work-in-progress Essays live outside the built collection.
- Local-first images. Covers and body images are committed, then optimized in place (16:9 covers, opaque sources to JPEG) and re-encoded to AVIF/WebP.
- Narration. An optional audio filename adds an in-page player for a Narration hosted on the fixed media domain.
- Semantic related essays, precomputed from sentence embeddings with taxonomy as an additional signal.
- Feeds and machine-readable indexes — a site feed plus one per section and
per topic, a sitemap index with real
lastmoddates,llms.txt, portable Markdown alternatives, and IndexNow updates. - Static redirects for legacy WordPress URLs — old post paths, feeds, paginated archives and downloads — so old links keep working.
Requires Node 24 (see .nvmrc) and pnpm 11.20.0 (pinned in package.json).
pnpm install
pnpm run devCI uses pnpm install --frozen-lockfile. Commit dependency changes with
pnpm-lock.yaml. Pre/post scripts stay enabled in pnpm-workspace.yaml so
builds still generate Markdown alternatives. Lighthouse can compare the
migrated site against older npm-based revisions without changing their tooling.
The dev server runs at http://localhost:4321. Scheduled essays render there so they can be proofread before they land.
Run the automated test suite before opening a pull request:
pnpm testThe command exits nonzero when a test fails. Its fixtures deliberately prove that formatting, content correctness, and production-build failures are all detected.
To check the production output:
pnpm run build
pnpm run previewNote
The postbuild step projects marked editorial regions into portable Markdown
alternatives. Use pnpm run build before checking the .md links advertised
in dist/llms.txt.
Important
Astro does not hot-reload astro.config.mjs, and .astro/ caches processed
Markdown. After changing a remark or rehype plugin, run rm -rf .astro and
restart the dev server, or you'll keep seeing the old output.
├─ src/
│ ├─ components/ # Astro components
│ ├─ content/
│ │ ├─ essays/<slug>/ # one folder per essay: <slug>.mdx plus its images
│ │ └─ drafts/ # work-in-progress Essays, not a built collection
│ ├─ layouts/
│ ├─ lib/ # content inventory, SEO/schema, and rendering helpers
│ ├─ pages/ # routes, RSS feeds, llms.txt
│ ├─ styles/global.css
│ ├─ consts.ts # site title, URL, description
│ └─ taxonomies.ts # section and topic descriptions
├─ scripts/ # build and maintenance CLIs — see Tooling
├─ data/ # generated but committed: semantic and publication state
├─ public/ # static assets, _headers, and legacy _redirects
└─ .github/workflows/ # correctness, publication, and related essays
Create src/content/essays/<slug>/<slug>.mdx and drop the images beside it.
---
title: What is a GPU and Why Does AI Need Them?
date: 2026-08-04
excerpt: GPUs are crucial for AI due to their ability to perform parallel calculations.
newsletterIntro: |-
GPUs do more than draw games. This essay explains why their parallel design
became essential to modern AI.
cover: ./gigabyte-gpu.jpg
coverAlt: The inside of a gaming PC lit in red and blue, with a graphics card above the motherboard.
categories:
- Programming
tags:
- AI
- Performance
audio: what-is-a-gpu.mp3
---| Field | Notes |
|---|---|
title |
Required. |
date |
Required YYYY-MM-DD; every essay publishes at 13:00 UTC. |
updated |
Optional later YYYY-MM-DD; feeds the sitemap's lastmod. |
cover / coverAlt / coverCaption |
Local path. Covers must be 16:9; alt text describes the image. |
excerpt |
Used for listings, metadata, feeds, and the on-page lead. |
newsletterIntro |
Required plain-text email introduction. |
categories / tags |
Sections and topics. At least one of each. |
sticky / cornerstone |
Feature an essay in its section / mark an evergreen link hub. |
downloads |
R2 files (file, optional label) or external HTTPS links (href, required label), rendered in the Downloads block. |
audio |
Optional filename served from static.buthonestly.io/audio/. |
Use standard Markdown links, including root-relative links to other essays.
Import Figure, Gallery, QuickSummary, Callout, and Blockquote from
src/components/content only when their extra semantics are needed.
| Command | What it does |
|---|---|
pnpm run dev |
Dev server on port 4321. |
pnpm test |
Runs the automated test suite, including deliberate CI-stage failure fixtures. |
pnpm run build |
Builds to dist/, then projects editorial Markdown alternatives. |
pnpm run lint |
Prettier check plus link check. |
pnpm run check:links |
Verifies canonical internal links, publication safety, and local assets. |
pnpm run links |
Prints advisory prose-link analysis; pass --json <path> for local JSON. |
pnpm run images [<slug>] |
Manually resizes and compresses oversized sources and converts opaque images to JPEG, printing renamed paths. |
pnpm run related |
Rebuilds the semantic related-essays map. |
pnpm run publication |
Verifies live content, deploys stale versions, resumes Kit delivery, and submits changed content to IndexNow. |
pnpm run narration --help |
Documents the staged local Narration workflow and every command option. |
The Narration tool is manual and local. It does not run as part of publication,
deploy the site, commit changes, or delete audio from R2. It accepts either an
Essay slug or the path to a directory-based MDX Essay, including a
work-in-progress Essay under src/content/drafts/.
Prerequisites:
- Node 24 dependencies installed with
pnpm install. ffmpegwith thelibmp3lameencoder (brew install ffmpegon macOS, or use the distribution package manager on Linux).- A billed Google Cloud project with the Vertex AI API enabled. The identity used for synthesis needs permission to call Vertex AI, normally the Vertex AI User role.
- For upload, a Cloudflare API token with Workers R2 Storage: Edit on the
account and Cache Purge: Purge on the site zone, plus the zone ID and the
R2 bucket behind
static.buthonestly.io.
Google authentication uses Application Default Credentials (ADC). For an interactive local identity, install the Google Cloud CLI and run:
gcloud auth application-default loginFor a service account or Workload Identity Federation configuration, set
GOOGLE_APPLICATION_CREDENTIALS to the absolute path of its ADC-compatible
credential file. Set GOOGLE_CLOUD_PROJECT when the credential does not supply
the project. Never commit credential files.
Project settings and secrets live in a 1Password Environment instead of a
plaintext .env. Install the latest beta 1Password CLI, enable its desktop-app
integration, copy the Environment ID from Developer → Environments → Manage
environment, and export that non-secret identifier:
export OP_ENVIRONMENT_ID=<environment-id>Run the stages through 1Password so each subprocess receives the Environment without persisting its values to disk:
op run --environment "$OP_ENVIRONMENT_ID" -- pnpm run narration prepare <Essay>
op run --environment "$OP_ENVIRONMENT_ID" -- pnpm run narration synthesize <Essay>
op run --environment "$OP_ENVIRONMENT_ID" -- pnpm run narration upload <Essay>
op run --environment "$OP_ENVIRONMENT_ID" -- pnpm run narration clean <Essay>Between preparation and synthesis, read and edit <slug>.audio.txt. Use
written-only and narration-only passages in MDX when the written and spoken
editions intentionally differ. Between synthesis and upload, listen to the
entire <slug>.mp3.
prepare (alias prep) writes the reviewed Narration script beside the Essay
and preserves an existing script. --refresh deliberately replaces it and
loses Narration-specific edits. The script is the synthesis input of record:
written-only passages are omitted and narration-only passages are included.
synthesize (alias synth) preflights ADC and ffmpeg, shows the voice, model,
style, pace, and chunk count, then requires typing yes before the paid request.
Use --yes to skip that prompt. --voice, --style, --pace, --model,
--region, --chunk-words, and --join-silence-ms override the defaults shown
by pnpm run narration --help and persist them in the script. Successful
chunks are checkpointed under local/narration/. Rerun the same command after a
partial provider failure to reuse them; edited chunks and provider-affecting
setting changes are synthesized again. Always listen to the complete MP3 after
synthesis, even when automated structural verification passes.
upload first validates that the MP3 matches the reviewed script. It then
preflights Cloudflare, uploads to R2, purges the exact public URL, verifies the
public bytes, and only then writes audio: <slug>.mp3 to Essay metadata. It
prompts only when replacing a different metadata filename; --yes skips that
prompt. Rerun upload after an upload, purge, or verification failure—the same
R2 key is safely overwritten and metadata remains unchanged until verification.
If the Essay changes concurrently after public verification, preserve that edit
and add the reported audio field manually.
The uploaded object uses max-age=0, must-revalidate for browser caches and a
one-year s-maxage for the Cloudflare edge. Exact-URL purge replaces the edge
copy immediately; a browser may retain bytes locally but must revalidate before
using them. clean is local-only: it removes the generated MP3, provenance
manifest, synthesis report, and chunk checkpoints while preserving the reviewed
Narration script, Essay metadata, and uploaded R2 object.
Generated MP3s, scripts, manifests, reports, and checkpoints are ignored by git. After upload, review the Essay metadata diff, run the normal verification, then stage and commit the MDX source. The Narration tool never performs these source-control steps.
| Workflow | Runs | Does |
|---|---|---|
ci.yml |
Pull requests, main pushes | Tests failure detection, formatting, content, and production build. |
publication.yml |
Hourly, essay pushes, manual | Deploys expected versions, resumes Kit broadcasts, and submits changed URLs to IndexNow. |
related.yml |
Essay pushes, manual | Regenerates and commits the semantic related-essay map. |
Scheduled runs matter because a date passing is not a push. The publication orchestrator makes an essay live within the hourly window. It records a Kit draft identity before delivery, waits until at least 13:15 UTC, and preserves Kit and IndexNow successes independently. Dependabot groups weekly npm and GitHub Actions updates, while GitHub security updates open separately when needed. GitHub's managed CodeQL setup scans Actions, JavaScript, and TypeScript changes and runs a weekly full scan.
A repository ruleset protects main with pull requests, the verify check,
resolved review threads, linear history, and squash-only merges. Administrators
can bypass the ruleset. The related, publication, and Lighthouse workflows read
REPOSITORY_DEPLOY_KEY from the repository's 1Password Environment for
generated-state commits. One checkpoint command restricts each workflow to its
named generated files, pins GitHub's SSH host keys, and removes its temporary
private-key file after every push attempt.
REPOSITORY_DEPLOY_KEY accepts a multiline private SSH key or the single-line
base64 encoding of the complete private-key file, including its header and
footer. Base64 fits the 1Password Environment text field; it is encoding, not
encryption, so treat the encoded value as a secret. The matching public key must
be registered as a GitHub repository deploy key with write access, and the
private key must not require a passphrase. On macOS, copy the encoded value
without printing it in the terminal:
base64 -i /path/to/private-key | tr -d '\n' | pbcopyPaste the clipboard into REPOSITORY_DEPLOY_KEY in the CI Environment. Use the
private-key file, not its .pub companion. Merge base64 support before changing
an existing multiline value, then rerun the failed workflow to verify a real
state checkpoint; an unchanged-state run does not exercise SSH authentication.
GitHub Actions installs the latest beta 1Password CLI and authenticates with the
OP_SERVICE_ACCOUNT_TOKEN repository secret. The non-secret
OP_ENVIRONMENT_ID repository variable selects the Environment. Provider
credentials are available only to commands wrapped by op run; the wrapper
removes the service-account token before starting the project command. Keep the
service account read-only and scoped to that Environment.
Cloudflare Pages builds dist/ from main. The publication orchestrator reads
each pending essay's data-content-version, requests the Pages deploy hook when
the expected hash is missing or stale, and waits for that exact version before
IndexNow follow-up. The hook is held as CF_DEPLOY_HOOK_URL in the 1Password
Environment. Two R2 buckets are served directly over custom domains:
downloads.buthonestly.io for essay downloads and
static.buthonestly.io for Narrations. See DOWNLOADS.md
for how to add a file.
Successful IndexNow hashes and Kit broadcast identities are committed to
data/publication-state.json. Kit keeps ownership of forms, contacts, consent,
broadcasts, and unsubscribes. The 1Password Environment requires KIT_API_KEY;
the optional KIT_EMAIL_TEMPLATE_ID pins the maintained account template. A
failed provider action remains pending while an independent success is
preserved; rerun publication.yml manually to recover without repeating
durably checkpointed work.
If Kit returns 404 for a recorded draft, publication looks for another draft
with the essay's marker and creates one only when none exists. Its identity is
checkpointed before a later phase can send it. Other API errors stop recovery;
a missing broadcast already marked delivery-requested requires manual
reconciliation. Out-of-band sends and deletions after sending must also be
reconciled before rerunning publication.
Important
wrangler.toml is git-ignored so the bucket names stay out of the public
repo. Deploying from a clone means recreating it, or setting the same R2
bindings in the Cloudflare dashboard.
Project environment variables:
| Variable | Used for |
|---|---|
FATHOM_SITE_ID |
Analytics, main-branch production builds only. |
CF_DEPLOY_HOOK_URL |
Cloudflare Pages deployment requests. |
KIT_API_KEY |
Kit broadcast lookup, draft creation, and delivery. |
KIT_EMAIL_TEMPLATE_ID |
Optional maintained Kit account template. |
SITE_URL |
Optional production-origin override for publication checks. |
GOOGLE_APPLICATION_CREDENTIALS |
Optional ADC-compatible credential file for Narration synthesis. |
GOOGLE_CLOUD_PROJECT |
Optional Google project override when ADC does not identify one. |
CLOUDFLARE_API_TOKEN |
Required for Narration upload; R2 edit and zone cache-purge permissions. |
CLOUDFLARE_ZONE_ID |
Required zone for exact-URL Narration cache purges. |
NARRATION_R2_BUCKET |
Required R2 bucket name for Narration upload. |
Local commands receive these values from a 1Password Environment. GitHub Actions uses the CI Environment for publication and generated-state secrets; Cloudflare Pages keeps its build-time variables in the Cloudflare dashboard.
The Fathom script is skipped when CF_PAGES_BRANCH is set to anything but
main, so preview deploys never pollute the stats even if the variable is set
for the Preview environment. To keep your own visits out, run
fathom.blockTrackingForMe() once in the browser console on the live site —
it persists in local storage (enableTrackingForMe() reverses it).