Skip to content
Boots Code Docs

Type to search…

↑↓to navigate
Esc

Publishing Runbook: New Article to Live on docs.bootsagent.com

The exact steps to add, preview, and ship an article on this site — one file, one command, about sixty seconds end to end. No git, no CI.

Guides2min read

This site deploys from your Mac straight to Vercel. There is no GitHub remote, no CI pipeline, and nothing that bills per push. The build runs locally (a few seconds) and only the finished static files are uploaded.

Terminal window
# 1. create the article
touch src/content/posts/en/my-new-lesson.md   # filename = URL slug


# 2. preview while writing
bun run dev                                    # → http://localhost:4321


# 3. ship it
bun run deploy                                 # ~10 seconds


# 4. confirm
open https://docs.bootsagent.com/posts/my-new-lesson

Everything below is the detail behind those four steps.

New file in src/content/posts/en/. The filename becomes the URL, exactly and case-sensitively:

  • supabase-rls-lessons.md → docs.bootsagent.com/posts/supabase-rls-lessons

Stick to lowercase-kebab-case.md so URLs stay clean and predictable.

Start from this template:

Minimum viable frontmatter
---
title: 'What I Learned About X'
description: 'One plain-text sentence for the card and search results.'
pubDate: 2026-08-02
tags: [supabase, typescript]
categories: [Runbooks]
---

Field When to add it
draft: true Work in progress — invisible on the live site, visible in local dev. Safe to deploy mid-draft.
mermaid: true The article contains charts/diagrams (```mermaid blocks)
math: true The article contains $LaTeX$ math
pinned: true Keep it at the top of the homepage
unlisted: true Live at its URL but hidden from all listings and search engines
updatedDate: When you revise an already-published article
heroImage: Featured image for the post top + listing card

Two traps:

  1. description is plain text — **bold** renders as literal asterisks on cards.
  2. Charts silently render as code blocks if you forget mermaid: true.

Standard markdown plus this site’s extras — callout alerts, code frames with titles and diff markers, Mermaid charts, KaTeX. The full syntax arsenal with live examples is in Make It Yours.

Images: make a folder next to your post (e.g. src/content/posts/en/assets/), drop the file in, reference it relatively — ![What it shows](./assets/screenshot.png). Astro optimizes it automatically.

Terminal window
bun run dev

Open http://localhost:4321. Edits hot-reload as you save. Check three things: the post page itself, its card on the homepage, and both themes (moon/sun toggle, bottom of the sidebar).

If it says the server is already running, it is — just open the browser. Stop it later with bunx astro dev stop.

Terminal window
bun run deploy

What this does, in order:

  1. astro build + Pagefind — full site build on your machine, search index included
  2. vercel deploy --prebuilt — uploads the finished files to the boots-astro-docs project (team Teamboots) and flips production

Success looks like this final line:

Aliased: https://docs.bootsagent.com

If the build fails, nothing ships — the live site stays on the previous version untouched. Frontmatter mistakes fail with an error naming the file and field (e.g. description over 280 chars); fix and rerun. Deploys are atomic: there is no half-deployed state.

Open https://docs.bootsagent.com/posts/<your-slug> — hard-refresh (Cmd+Shift+R) if you had the page open before. New content is immediately searchable (/ key) because the search index shipped with the deploy.

I want to… Do this
Revise a published article Edit the file, add updatedDate:, bun run deploy
Unpublish an article Delete the file (or set draft: true), bun run deploy
Share privately before launch unlisted: true, deploy, send the direct URL
Fix a typo site-wide fast Edit → bun run deploy — 10 seconds is the whole cycle

Symptom Cause → fix
Deploy fails naming my new file + a field Frontmatter schema — fix that field, rerun
Chart shows as a text code block Add mermaid: true to frontmatter
Post missing from homepage draft: true or unlisted: true still set
Card shows literal **asterisks** Descriptions are plain text — remove markdown
vercel: not logged in (rare) vercel login, then deploy again

This post shipped via its own step 4.