The publish loop
The explicit local-to-public boundary, checks, and why a merge is not a deploy.
Three commands and one rule. The rule is that a clean build is not a deploy.
Where things publish
master. It is GitHub’s default branch and the branch Netlify builds, and
those two being the same is deliberate.
They disagreed once, on 2026-09-22, and it cost a day: four entries were merged
onto release/pub-v0.1.0, every build was clean, the publish script reported
success four times, and nothing reached the site. Netlify’s production branch
lives in its console and no key in netlify.toml sets it, so nothing in the
repo could have told you. There is a comment at the top of netlify.toml now
that says so. If the console setting ever changes, change that comment in the
same sitting.
Local and public
Every page is in one of two states, and local is the default.
| State | Front matter | Built for |
|---|---|---|
| public | draft = false |
www.jwogrady.com, previews, and local |
| local | anything else | http://localhost:8080/ only |
A cascade in hugo.toml gives every page draft = true unless it says
otherwise. A page that leaves the key out is local, not public, so nothing
reaches the site by omission. Going public is always an explicit
draft = false, and story.sh publish is what writes it.
Netlify never passes -D, so it builds public pages only. Locally, one
command builds everything and serves it from the jwogrady wslc container:
bin/local-preview # build the working tree, local + public, and serve it
bin/local-preview --build-only # same build, into ./public-local
It builds the working tree as it stands, uncommitted edits included, with
drafts and future-dated pages. It also folds in any entry still sitting on an
unmerged story/* or wip/* branch. Its robots.txt says Disallow: /.
The loop
The lifecycle is a script, so the git mechanics are not re-improvised per entry:
.claude/skills/disbatch/scripts/story.sh plan <slug> [title...]
.claude/skills/disbatch/scripts/story.sh check [slug]
.claude/skills/disbatch/scripts/story.sh publish <slug>
.claude/skills/disbatch/scripts/story.sh list
plan branches story/<slug>, assigns the next citation handle by
scanning the existing entries, dates the entry a minute in the past, and
scaffolds the six beats as comments.
The date matters: Hugo silently drops future-dated content. A stamp even a minute ahead produces a 404 with no error and no warning.
check builds with and without drafts, then reports TODO markers, word
count, figures, tags, and whether the page actually rendered. renders NO with
a plausible-looking entry almost always means the date is in the future.
publish refuses an entry that still has TODO markers or no tags — the
second would render and appear in no index, which has happened. Then it
undrafts, verifies the page survives a production build, commits, merges
--no-ff onto master and deletes the branch.
list is every entry with its handle, state and length, plus the tag
counts and the number of distinct counts — that number is how many hue bands
the index can draw.
By hand, without the script
hugo new posts/what-i-learned-today.md # or a bundle, below
hugo server -D # preview, drafts included
hugo --gc --panicOnWarning # what the host runs
For an entry with its own image, make it a page bundle, because that is what lets the theme resize and convert:
mkdir content/posts/my-entry
hugo new posts/my-entry/index.md
# images go in content/posts/my-entry/, beside index.md
The difference is shipping a 1.7 MB PNG or a 37 KB WebP.
Check before pushing, and after
hugo --buildDrafts # does it build at all
hugo # does it build without drafts
The second one matters: an entry that renders under -D and vanishes in
production is the most common way to publish nothing.
And then the part that is easy to skip, because the script has already said
published:
curl -s -o /dev/null -w '%{http_code}\n' https://www.jwogrady.com/posts/<slug>/
A merge is not a deploy and a deploy is not a page. The only evidence that
something published is the live URL answering 200.
Capture without publishing
Lab Notes do not need the six-beat article scaffold. Use the site-owned
bin/lab tool to start with one observation, a selected excerpt or an
experiment. It always writes draft = true, never commits, and never
pushes. Capture does not imply approval.
bin/lab new first-observation --title 'A useful observation' --tag workflow
bin/lab from-markdown selected-conversation /path/to/selected-excerpt.md --tag workflow
bin/lab from-logseq selected-finding --block BLOCK-UUID --tag workflow
bin/lab from-notebook experiment /path/to/experiment.ipynb --tag experiments
Select a Logseq block explicitly; the tool does not read the journal, scan
the graph, follow block references or export children. Add --block again
for another block. It uses the existing local logseq-api helper, whose
token is read from 1Password at use time. A block marked private:: true
is refused. References to unselected blocks must be resolved or removed.
Assets are opt-in too: --asset /path/to/screenshot.png copies that file,
not the surrounding folder. Add context and alt text before publication.
Review excerpts for other people’s private details, tokens and client data.
The tool cannot make that judgment for you.
Notebook capture reads a saved .ipynb file; it never runs a kernel. Outputs
are omitted by default. --include-outputs opts into stored plain text and
PNG/JPEG output, not HTML, JavaScript or widgets. Review generated images,
replace their placeholder alt text, and do not treat old outputs as a fresh
execution. Select the original notebook with --asset only if it is safe to
offer as a download.
Review, then explicitly make a note public
bin/lab check first-observation
# Review the exact text AND assets corresponding to the printed hash.
bin/lab publish first-observation --approve-sha256 REVIEWED-HASH
check performs mechanical checks and prints a hash of the bundle. That is
not human approval. publish requires that exact hash and changes only the
selected note’s draft flag. Any edit or asset change invalidates an older
hash. This is a local operation, not a commit, push, merge or deployment.
Use the normal reviewed Git release process afterward, and check the live
URL. Do not run the older Journal story.sh publish over a dirty working
tree: it stages all changes, not just the story.
Preview drafts on loopback only (hugo server -D --bind 127.0.0.1 --port 1317).
The production build must run without -D. /index.xml is Journal-only;
/lab-notes/index.xml is Lab Notes-only. Tags, projects and archives are
shared indexes with explicit writing-type labels. There is no site search
in the current theme; these indexes are the discovery paths.