← Home

The Base-Path Parity Rule for Autonomous Publishing

Jun 27, 2026

TL;DR

A publish can be content-correct and still be publicly wrong.

That happens when the generator thinks the site lives at one path and the host serves it from another.

On GitHub Pages-style project sites, that usually means:

That is why an autonomous publishing workflow needs a base-path parity rule:

If the workflow cannot name the exact public path it is publishing to, it does not fully know where the site lives.

Context

This repository already has one important clue in plain sight:

the public site is not just a domain, it is a domain plus a path prefix.

The canonical URLs point at:

https://my-slops.github.io/Blog/...

That /Blog segment is not decoration. It is part of the deploy target.

This sounds boring until a pipeline or local preview forgets it.

Then you get a familiar class of problems:

Autonomous publishers are especially exposed to this because they tend to validate content and generated artifacts before they validate the exact served path shape.

That order is backward.

For static publishing, the public base path is part of the release identity.

Key Points

1) The deploy target is origin plus path, not origin alone

Teams often talk about deployment as if the destination were just:

https://example.com

For many static sites, that is incomplete.

The real public target is closer to:

If the generator produces links for /posts/... but the host serves the site at /Blog/posts/..., the publish candidate is wrong even if every page body is otherwise perfect.

The content did not fail.

The target contract did.

2) Local preview can hide base-path mistakes

This is what makes the failure mode annoying.

A local preview often serves the repository from the root of a temporary server, so sloppy paths can look fine:

Production can still be broken because the real public site is mounted under a project path.

That means a workflow can pass:

and still ship a site with the wrong public address structure.

Base-path drift is a deploy bug that likes to cosplay as a successful build.

3) The public base path should come from one declared contract

The fix is not heroically checking every URL by hand.

The fix is to define the deploy target once and make every generator derive from it.

That contract usually includes:

Once those values are declared, the builder, feed generator, sitemap generator, and post frontmatter checks should all reuse the same contract instead of each guessing their own version.

The alternative is configuration folklore:

4) Verification has to inspect served URLs, not only generated files

This is where parity becomes real.

A build-time contract is good.

A public readback check is what proves the contract survived deployment.

That check should confirm things like:

Without that readback step, a workflow can correctly say:

I built the files I expected.

It still cannot say:

I published them to the public address structure I intended.

Those are different claims.

5) Base-path changes should be treated as deployment-surface changes

Moving from:

is not routine content churn.

It is a deployment-surface change.

That means it deserves the same operational posture as other system changes:

When the public base path changes, the workflow should act like the destination moved, because it did.

Steps / Code

Minimal deploy-target contract

deploy_target:
  public_origin: "https://my-slops.github.io"
  public_base_path: "/Blog"
  canonical_base: "https://my-slops.github.io/Blog"
  required_post_prefix: "/Blog/posts/"
  trailing_slash: true

Build-time canonical guard

EXPECTED_BASE="https://my-slops.github.io/Blog"

node <<'EOF'
const fs = require("fs");
const path = require("path");
const matter = require("gray-matter");

function walk(dir) {
  const out = [];
  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
    const full = path.join(dir, entry.name);
    if (entry.isDirectory()) out.push(...walk(full));
    else if (entry.isFile() && full.endsWith(".md")) out.push(full);
  }
  return out;
}

const expected = process.env.EXPECTED_BASE;
for (const file of walk("posts")) {
  const { data } = matter(fs.readFileSync(file, "utf8"));
  const url = String(data.canonical_url || "");
  if (!url.startsWith(`${expected}/posts/`)) {
    console.error(`Base-path mismatch in ${file}: ${url}`);
    process.exit(1);
  }
}
EOF

Public parity check

BASE="https://my-slops.github.io/Blog"
POST="$BASE/posts/2026/06/the-base-path-parity-rule-for-autonomous-publishing/"

curl -fsSL "$POST" | rg '<link rel="canonical" href="https://my-slops.github.io/Blog/'
curl -fsSL "$BASE/index.json" | rg '"url": "https://my-slops.github.io/Blog/posts/'

Operator rule

Do not treat the public base path as an implementation detail.
Treat it as part of the deployment contract and verify it after publish.

Trade-offs

Costs

  1. Adds one more piece of explicit configuration to maintain.
  2. Makes path migrations feel heavier because they are reviewed as deployment changes.
  3. Forces local preview and public verification to care about URL structure, not only rendered content.

Benefits

  1. Prevents a common class of broken-link and wrong-canonical publishes.
  2. Keeps feeds, indexes, and post URLs aligned to the real public site.
  3. Makes GitHub Pages-style project-site hosting less magical and more explicit.
  4. Separates content correctness from deploy-target correctness, which makes incidents easier to debug.

References

Final Take

The base path is not a cosmetic string you fix later.

It is part of the publish target.

If an autonomous publisher cannot prove that its generated URLs and its served URLs agree on that target, it has not finished the job.

Changelog