My static site deploys by hand, so publishing meant dropping a batch of articles at once, and each one needed inbound links and fresh translations before the build's checks passed. Here's the queue folder, schedule file and guarded wrapper that now publish one or two a day.
The site is Amyloid Test, but nothing here is specific to it. You need markdown files, a build with content checks, and a scheduler.
The layout
Each finished post waits in its own folder:
seo/queue/<slug>/en.md seo/queue/<slug>/de.md seo/queue/<slug>/es.md seo/queue/<slug>/links.json seo/queue/schedule.json schedule.json is a list of { "at": "<ISO date-time>", "slug": "<slug>" }. To hold a post back, delete its line. To stop everything, empty the file to [].
links.json exists because my build refuses an article with fewer than three inbound links. It lists one sentence per language, aimed at an existing article, that links to the new one:
[ { "target": "existing-slug", "en": "...", "de": "...", "es": "..." } ] On publish, each sentence is appended to its target article. A new post arrives with its inbound links already in place.
check: validate before anything moves
node scripts/seo-queue.mjs check validates every queued post. This is the core, trimmed:
function check(slug, live) { const problems = []; const dir = join(QUEUE, slug); for (const locale of LOCALES) if (!existsSync(join(dir, `${locale}.md`))) problems.push(`missing ${locale}.md`); if (!existsSync(join(dir, "en.md"))) return problems; if (live.has(slug)) problems.push("slug is already live"); const counts = {}; for (const locale of LOCALES) { const file = join(dir, `${locale}.md`); if (!existsSync(file)) continue; const { fm, body } = split(readFileSync(file, "utf8")); if (fm.slug !== slug) problems.push(`${locale}: slug field is "${fm.slug}"`); // links, headings, table rows: these counts must match across languages counts[locale] = [ (body.match(/\]\(/g) ?? []).length, (body.match(/^#{2,3}\s/gm) ?? []).length, (body.match(/^\|/gm) ?? []).length, ].join("/"); for (const [, target] of body.matchAll(/\]\(\/resources\/([a-z0-9-]+)\/?\)/g)) if (!live.has(target)) problems.push(`${locale}: links to /resources/${target}/, which is not live`); } if (new Set(Object.values(counts)).size > 1) problems.push(`structure differs between languages: ${JSON.stringify(counts)}`); const linksFile = join(dir, "links.json"); const links = existsSync(linksFile) ? JSON.parse(readFileSync(linksFile, "utf8")) : []; if (links.length < 3) problems.push(`links.json has ${links.length} inbound links, needs 3`); for (const link of links) { if (!live.has(link.target)) problems.push(`links.json target ${link.target} is not live`); for (const locale of LOCALES) if (!String(link[locale] ?? "").includes(`](/resources/${slug}/)`)) problems.push(`links.json ${link.target} ${locale}: no link to /resources/${slug}/`); } return problems; } The structure check is the cheap trick I like most. If the German file has a different number of links, headings or table rows than the English one, a translation dropped something. It also catches links to posts that are still in the queue, since they aren't live yet.
publish: move what's due
node scripts/seo-queue.mjs publish picks every schedule entry whose at is in the past, re-runs check, and refuses to continue if it fails. For each due post it:
- copies the three files into the content folder, stamping
publishDateandupdatedAtwith the date part of the schedule entry; - appends each
links.jsonsentence to its target article in all three languages, and bumps that article'supdatedAt; - re-stamps the translation cache for the new post and every touched target, by hashing the English source again, so the build doesn't think the translations are stale;
- deletes the queue folder, removes the entry from
schedule.json, and adds a line to a log file.
publish --dry-run only prints which slugs are due, which the wrapper uses.
The wrapper: a build that can say no
A scheduler runs scripts/seo-publish.sh twice a day. It works in its own clone, so my working copy is never touched. Guard first (trimmed: the real script also logs timestamps):
set -euo pipefail tree="$HOME/.seo-publish" lock=/tmp/seo-publish.lock mkdir "$lock" 2>/dev/null || { echo "previous run still going"; exit 0; } trap 'rmdir "$lock"' EXIT [ -d "$tree/.git" ] || git clone -q https://github.com/<your-org>/<your-repo>.git "$tree" cd "$tree" git fetch -q origin main git checkout -q -f -B main origin/main git clean -qfd src/content/resources seo due=$(node scripts/seo-queue.mjs publish --dry-run) if [ "$due" = "nothing due" ]; then echo "nothing due"; exit 0; fi lock_hash=$(shasum package-lock.json | cut -d' ' -f1) if [ "$(cat node_modules/.lock-hash 2>/dev/null)" != "$lock_hash" ]; then npm ci --no-audit --no-fund --loglevel=error echo "$lock_hash" > node_modules/.lock-hash fi # The backend and the static site must ship from the same commit. This job only # deploys the site, so it stops if backend code changed since the live deploy. live=$(npx wrangler pages deployment list --project-name <your-pages-project> 2>/dev/null \ | awk -F'│' '/Production/ { gsub(/ /, "", $5); print $5; exit }') if [ -z "$live" ] || ! git cat-file -e "$live^{commit}" 2>/dev/null; then echo "cannot read the live commit; not publishing"; exit 1 fi if ! git diff --quiet "$live" HEAD -- convex; then echo "convex/ changed since the live deploy; deploy both together first"; exit 1 fi The failure path is what makes unattended runs safe (trimmed again: the real commit message lists the published slugs, and an IndexNow ping follows the deploy):
node scripts/seo-queue.mjs publish if ! npm run build > /tmp/seo-publish-build.log 2>&1; then echo "build failed, nothing pushed; see /tmp/seo-publish-build.log" tail -20 /tmp/seo-publish-build.log git checkout -q -f -B main origin/main && git clean -qfd src/content/resources seo exit 1 fi git add seo src/content/resources git commit -q -m "content: publish queued articles" git push -q origin main npx wrangler pages deploy dist --project-name <your-pages-project> --branch main \ --commit-hash "$(git rev-parse HEAD)" --commit-message "content: publish queued articles" The order matters. Publishing happens in the throwaway clone, the full build runs with every gate, and only a green build gets committed, pushed and deployed. A red build resets the clone and leaves the post queued, so the next run retries. Nothing bad reaches the remote.
What I'd do differently
- Use a hosted scheduler. My scheduler is launchd on a laptop. A slot missed during sleep runs when the machine wakes, two missed slots collapse into one run, and nothing runs while the laptop is off. A CI schedule or a small VPS cron job would be more reliable.
- Parse the deploy table properly. Reading the live commit by splitting a CLI table on a box-drawing character works until the CLI changes its output. A JSON output flag, if your tool has one, is better.
- Alert on failure. Right now a failed run writes to a log file. A message to me would be better.
Publishing is mostly boring plumbing. The part worth copying is the order: check, move, build, and only then push.
The queue publishes into the resources section.
I run Amyloid Test, a small health-information site with an at-home lab test. The code above is from its publishing pipeline.