DEV Community

Tim Ottowitz
Tim Ottowitz

Posted on

Scheduled posts for a static site without a CMS: a queue folder, a cron slot, a build that can say no

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
Enter fullscreen mode Exit fullscreen mode

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": "..." }
]
Enter fullscreen mode Exit fullscreen mode

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;
}
Enter fullscreen mode Exit fullscreen mode

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 publishDate and updatedAt with the date part of the schedule entry;
  • appends each links.json sentence to its target article in all three languages, and bumps that article's updatedAt;
  • 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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)