Skip to content

docs: fill missing description and canonical frontmatter fields - #735

Open
Iheanacho-ai wants to merge 1 commit into
siderolabs:mainfrom
Iheanacho-ai:add-frontmatter
Open

docs: fill missing description and canonical frontmatter fields#735
Iheanacho-ai wants to merge 1 commit into
siderolabs:mainfrom
Iheanacho-ai:add-frontmatter

Conversation

@Iheanacho-ai

Copy link
Copy Markdown
Member

What

Backfilled missing description and canonical frontmatter fields across Talos version pages, plus two unversioned pages missing description.

Why

Several pages were missing SEO-relevant frontmatter that sibling versions of the same page already had.

Change

  • 43 missing description fields — 34 copied from a sibling version's frontmatter for the same page, 9 hand-written where no version had one (learn-more/talos-for-linux-admins, learn-more/talos-platform-configuration, and one Omni + one Kubernetes Guides page).
  • 114 missing canonical fields (Talos only) — pointed at each page's v1.13 (latest stable) URL, or v1.14 for pages that only exist in that unreleased version.

Testing

  • Ran make broken-links, make validate-docs-nav, make docs.json (no diff), make style-check-changed-local — all pass, 0 new errors.
  • Verified: valid YAML frontmatter on all 157 changed files, no duplicate keys, no unintended content changes (diff is additive, only description:/canonical: lines).
  • By: agent (Claude), local checks only.

@github-project-automation github-project-automation Bot moved this to To Do in Planning Sep 3, 2026
@talos-bot talos-bot moved this from To Do to In Review in Planning Sep 3, 2026
@smira smira removed this from Planning Sep 3, 2026
@sterlingkoch

Copy link
Copy Markdown
Member

Reviewed alongside #733, since they overlap heavily. Two things worth knowing before this goes further.

1. All 114 canonical additions here are byte-identical to #733's generated output. I compared every overlapping file: 114 in common, zero disagreements on the value. So the canonical half of this PR is the hand-maintained version of something #733 makes a tool for. The 43 description backfills are the real contribution and they're good.

2. The v1.13 premise has expired, and 50 v1.14 pages point backward as a result. "v1.13 (latest stable)" and "v1.14 for pages that only exist in that unreleased version" were both true when this was written. v1.14.0 is final and in main now, so v1.13 isn't latest stable and v1.14 isn't unreleased. Representative: public/talos/v1.14/configure-your-talos-cluster/hardware-and-drivers/hailo.mdx:4. Full list:

git diff origin/main...HEAD -- 'public/talos/v1.14/*' | rg '^\+canonical:.*v1\.13'

On the general question of pointing a canonical at an unreleased version: here it turned out harmless, because those v1.14 pages were already published and all 52 self-canonicals resolve 200. But the reasoning was fragile rather than correct. A canonical aimed at an unpublished page tells Google the indexable copy is something it can't fetch, which suppresses the page that does exist. Safer rule is that a page canonicalizes to itself until a published successor exists, which is what #733's hasEquivalentAt enforces structurally and hand-editing can't.

3. The conflicts are all against main, none against #733. 13 files: the nine learn-more pages (talos-for-linux-admins.mdx and talos-platform-configuration.mdx across v1.11 to v1.14) and four platform-specific-installations/virtualized-platforms/opennebula.mdx (v1.6 to v1.11). Every one is the same shape, a description: inserted next to a canonical: line that main independently bumped to v1.14. Full list with git merge-tree --write-tree --name-only origin/main HEAD. They all resolve by taking main's canonical and keeping the added description, and they disappear entirely if the canonical half comes out.

The descriptions themselves are clean. Across all 157 files I verified valid YAML frontmatter, zero duplicate keys, no unquoted colons, no apostrophe quoting hazards, and no content changes anywhere. The diff really is additive as described.

Nit: quoting is inconsistent, bare at v1.10/advanced-guides/migrating-from-kubeadm.mdx:4 versus quoted at v1.10/platform-specific-installations/virtualized-platforms/kvm.mdx:4, and voice drifts between gerund ("Creating a Talos Kubernetes cluster on OpenNebula.") and imperative ("Create a Talos Kubernetes cluster with KVM."). The gerunds came from sibling versions, so they're inherited rather than introduced.

@sterlingkoch sterlingkoch left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See inline comments (most are agent-to-agent comments).

Signed-off-by: Amarachi Iheanacho <amarachi.iheanacho@siderolabs.com>
@Iheanacho-ai

Copy link
Copy Markdown
Member Author

rebased and updated @sterlingkoch

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants