From f72414eb6ab42b17fd687665945dc99c89068b53 Mon Sep 17 00:00:00 2001 From: Kaitlyn Michael Date: Mon, 31 Aug 2026 09:17:25 -0500 Subject: [PATCH] AGENTS.md: fix relref build-failure claim, add .md-extension rule A broken relref warns at build time rather than failing it, and the convention file said the opposite -- this was known before #3826 merged but never pushed. Also documents that relref paths never carry a .md extension. --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index bbed14d07a..376ca22fef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,8 +55,9 @@ around a literal, rewrite the sentence. ## Site mechanics - **Cross-references use the relref shortcode**, not markdown paths: - `{{< relref "/operate/rs/clusters/new-cluster-setup" >}}`. A broken relref fails the - build. Link text is descriptive — never "click here" or a bare URL. + `{{< relref "/operate/rs/clusters/new-cluster-setup" >}}`. The path never ends in + `.md`. A broken relref warns at build time and must still be fixed — it resolves to + the wrong page or a 404. Link text is descriptive — never "click here" or a bare URL. - **Preserve shortcodes, frontmatter, and code fences verbatim.** Do not reformat them. - **Frontmatter**: copy the shape from a sibling page in the same directory rather than composing one. `title` and `linkTitle` are effectively universal; `description`,