From fe2781ccf44e85ec0778df6cbe8ae77620673f1a Mon Sep 17 00:00:00 2001 From: Branimir Georgiev Date: Sun, 26 Apr 2026 09:31:52 +0300 Subject: [PATCH] docs: add recipe-to-recipe link convention to CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the three link patterns (chapter→chapter, chapter→recipe, recipe→recipe) with examples. Prevents repeat of the broken sibling link bug from #187. Co-Authored-By: Claude Opus 4.6 (1M context) --- CLAUDE.md | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 8718b49..2ab55ff 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -101,14 +101,20 @@ Every chapter follows this structure: ### 2.4 Cross-references -- Reference other chapters by file: `[Building Blocks](02-building-blocks.md)` - Reference sections within a chapter by heading anchor: `[Tag Object](#tag-object-labels)` -- Markdown links must use the **URL path** (driven by `section` frontmatter), - not the filesystem path — the remark plugin - (`astro-site/src/plugins/remark-rewrite-links.ts`) rewrites links at - build time -- Recipe pages live in `chapters/recipes/` but their URLs are - `/playbook/...` — link to them as `playbook/X.md`, not `recipes/X.md` +- The remark plugin (`astro-site/src/plugins/remark-rewrite-links.ts`) + rewrites `.md` links at build time — use the correct format depending + on source and target: + +| From → To | Link format | Example | +|-----------|-------------|---------| +| Chapter → chapter | `NN-slug.md` | `[Glossary](09-glossary.md)` → `../glossary/` | +| Chapter → recipe | `playbook/slug.md` | `[Debugging](playbook/debugging.md)` → `../playbook/debugging/` | +| Recipe → recipe | `../slug/` (raw URL) | `[Hooks](../hooks/)` — rewriter ignores it, browser resolves correctly | + +- **Never use `slug.md`** for recipe-to-recipe links — the sibling + rewriter turns it into `slug/` which resolves to + `/playbook/current/slug/` instead of `/playbook/slug/` ### 2.5 Images