From 0119cad22c69a36bae9761055a8ffca79aaa704b Mon Sep 17 00:00:00 2001 From: Derek Lewis Date: Mon, 31 Aug 2026 20:13:25 +0000 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=F0=9F=94=A7=EF=BC=9Apoint=20the=20?= =?UTF-8?q?handbook's=20cross-links=20at=20pages?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six link definitions in the style handbook named the file beside them, `./capitalization.md` and the like. On the built site a page is a directory, so those resolved under the page doing the linking -- `/docs/handbook/style/colons/capitalization.md` -- and returned 404 in production. Every one of them was broken for a reader. They were written that way for a reason: `remark-validate-links` resolves a link against the filesystem, so a site URL fails the check that a neighboring file passes. Absolute URLs satisfy both, since the validator does not follow anything off the disk, and they stay correct when the handbook is read on GitHub rather than on the site. The cost is that a link followed from a deploy preview lands on the published site instead of the preview. Rewriting these at build time would avoid that, at the price of machinery that has to know how a source path becomes a URL. Signed-off-by: Derek Lewis Assisted-by: Claude-Code:claude-opus-5 --- collections/_docs/handbook/style/code-syntax.md | 2 +- collections/_docs/handbook/style/colons.md | 12 ++++++------ 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/collections/_docs/handbook/style/code-syntax.md b/collections/_docs/handbook/style/code-syntax.md index a260860bb..f17f55905 100644 --- a/collections/_docs/handbook/style/code-syntax.md +++ b/collections/_docs/handbook/style/code-syntax.md @@ -145,7 +145,7 @@ parameter global-flag. -[Explaining placeholders]: ./code-in-text.md#explaining-placeholders +[Explaining placeholders]: https://open.inf.is/docs/handbook/style/code-in-text/#explaining-placeholders diff --git a/collections/_docs/handbook/style/colons.md b/collections/_docs/handbook/style/colons.md index f5ebf2a45..c7bf56abc 100644 --- a/collections/_docs/handbook/style/colons.md +++ b/collections/_docs/handbook/style/colons.md @@ -75,12 +75,12 @@ For information about when it's better to use colons than dashes, see -[Some specific items to put in code font]: ./code-in-text.md#some-specific-items-to-put-in-code-font -[capitalization]: ./capitalization.md -[Classification]: ./commit-messages.md#classification -[list introductions]: ./lists.md#intros -[code-sample introductions]: ./code-samples.md#intros -[Dashes]: ./dashes.md#colons +[Some specific items to put in code font]: https://open.inf.is/docs/handbook/style/code-in-text/#some-specific-items-to-put-in-code-font +[capitalization]: https://open.inf.is/docs/handbook/style/capitalization/ +[Classification]: https://open.inf.is/docs/handbook/style/commit-messages/#classification +[list introductions]: https://open.inf.is/docs/handbook/style/lists/#intros +[code-sample introductions]: https://open.inf.is/docs/handbook/style/code-samples/#intros +[Dashes]: https://open.inf.is/docs/handbook/style/dashes/#colons [the Japanese colon]: https://wikipedia.org/wiki/Japanese_punctuation#Colon