From 56278bdda3806eabcfb98db9981052a96e12c50d Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Sat, 23 May 2026 08:12:15 -0400 Subject: [PATCH] fix: clarify within-collection vs cross-collection link conventions Closes #245 Replace the ambiguous "Use absolute paths when pointing to files from other sections" with explicit guidance distinguishing: - Within a versioned collection: use relative links to avoid silently crossing version boundaries when a new major version is added - Across collections: use absolute paths Signed-off-by: Michael Harp --- CONTRIBUTING.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 606e2a343..ea1228056 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -89,7 +89,9 @@ Use the following terms for the individual components: ### Linking -- Don't use URI for links pointing to files form this documentation -- Use URI when referring to remote locations -- Use absolute paths when pointing to files from other sections -- Use filename only without path when referring to a file in the same directory +- Within a versioned collection (e.g. `docs/_openvox_8x/`), use relative links (`page.html`) + rather than absolute `/openvox/latest/page.html` links. Absolute `/latest/` links silently + cross version boundaries when a new major version is added. +- Prefer `page.html` over `./page.html` — the leading `./` is unnecessary. +- When linking across collections (e.g. from `_openvox_8x/` to `_openvoxdb_8x/`), use absolute paths (`/openvoxdb/latest/page.html`). +- Use full URIs for external links only.