STATIC // NORTH
← Guides

GUIDE / DOCUMENTATION

Publishing Updates to Static North

A dependable local-to-live workflow for adding articles, checking changes, deploying through GitHub, and rolling back safely.

Static North has three copies of the site, each with a different job:

  • your local project folder is where you write and test changes;
  • GitHub is the source of truth and history of every published version;
  • the VPS runs the public site, but it is not where you edit files.

The normal loop is: make a change locally, check it, commit it, push it, then let GitHub deploy it to the VPS.

Add or update an article

Articles are MDX files in content/. Choose the collection that fits the article:

content/fixes/       → /fixes/
content/guides/      → /guides/
content/scripts/     → /scripts/
content/recipes/     → /recipes/
content/downloads/   → /downloads/

Copy a nearby article, rename it with a lowercase hyphenated filename, then update its frontmatter. For example, this file is available at:

content/guides/publishing-static-north-updates.mdx
→ /guides/publishing-static-north-updates

The minimum useful frontmatter is:

---
title: "A clear, specific title"
description: "A short summary that works in archive cards and search results."
type: "guide"
category: "Documentation"
tags:
  - Git
  - Deployment
date: "2026-08-30"
draft: false
---

Use draft: true while an article is unfinished. Drafts stay out of the homepage, collection pages, search, tags, and public routes.

Preview locally

From the project folder, start the local development site:

npm run dev

Open the address it prints, usually http://localhost:3000. Check the new article’s URL, headings, code blocks, tags, related entries, and mobile layout before publishing. Stop the server with Ctrl+C when you are finished.

Run the pre-publish checks

Run these from the project root before you commit:

npm run typecheck
npm run lint
npm run build -- --webpack

The build command creates a production version locally. The --webpack flag is intentional for this workstation: it avoids a local Turbopack sandbox limitation. GitHub runs the same checks again before it deploys anything.

If a check fails, fix the reported issue locally and run that check again. Do not push a known failure just to see whether the live server accepts it.

Commit and push

First, inspect what changed:

git status
git diff

Then stage only the files you mean to publish, make a short commit, and push it:

git add content/guides/your-new-article.mdx
git commit -m "Add guide for publishing updates"
git push

Use a plain-language commit message that describes the result, not the process. Examples:

Add SSH key permissions fix
Correct pizza dough baking temperature
Update Exchange authentication guide

What happens after git push

Pushing to the main branch starts the Deploy Static North workflow in GitHub Actions. It:

  1. installs the exact dependencies recorded in package-lock.json;
  2. runs the TypeScript, lint, and production-build checks;
  3. uploads the checked source to the VPS using a dedicated deploy key;
  4. rebuilds and restarts the Docker container; and
  5. confirms the application answers successfully before calling the deployment complete.

Open the repository’s Actions tab to watch it. A successful run means the new commit is live at staticnorth.eighty6.ca.

Most releases take a few minutes because the VPS builds a fresh production container. You do not need to SSH into the server while the workflow runs.

Verify the public site

After the Action has a green checkmark, open the article’s public URL in a normal browser. Check the heading, metadata, formatting, links, and any commands carefully enough to make sure the page says what you intended.

For a new guide named my-new-guide.mdx, the URL would be:

https://staticnorth.eighty6.ca/guides/my-new-guide

If the content looks wrong but the deployment succeeded, fix it in the local file and repeat the same commit-and-push process. GitHub keeps the complete history, so every correction is traceable.

When a deployment fails

A failed GitHub Action does not publish the failed commit. The previous working version stays online.

Open the failed job in GitHub Actions and read the first meaningful error. Common causes are an MDX syntax mistake, missing frontmatter, a TypeScript error, or a failed link/component build. Fix the problem locally, run the relevant check, commit the correction, and push again.

Only retry the exact same workflow when the failure is clearly temporary—for example, a GitHub runner or network outage. For code or content errors, make a new correcting commit instead.

Roll back a published change

If a published update needs to come down, revert its Git commit rather than editing the VPS:

git log --oneline
git revert COMMIT_SHA
git push

Replace COMMIT_SHA with the short identifier shown by git log. Git creates a new commit that reverses the selected one, and the normal deployment workflow publishes that rollback.

This is safer than rewriting history because it leaves a clear record of both the original change and the recovery.

A compact publishing checklist

Before pushing, confirm:

  • the article is in the correct content/ collection;
  • its filename and frontmatter are accurate;
  • draft is set correctly;
  • you previewed the intended URL locally;
  • typecheck, lint, and build passed; and
  • git status shows only changes you expect.

After pushing, confirm:

  • the Deploy Static North Action has a green checkmark; and
  • the live article reads correctly at its public URL.

That is the whole system: write locally, keep GitHub as the record, and let the automated deployment update the VPS.

Keep following the thread

Related notes