From 528f2bcec150c9867690da1da828305e8f815eb7 Mon Sep 17 00:00:00 2001 From: Dana Breseman Date: Fri, 1 May 2026 11:16:57 +0200 Subject: [PATCH] Update Claude's link guidance --- .claude/scripts/resolve-doc-url.sh | 2 +- CLAUDE.md | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.claude/scripts/resolve-doc-url.sh b/.claude/scripts/resolve-doc-url.sh index 4af6c42229e..80951fc244f 100644 --- a/.claude/scripts/resolve-doc-url.sh +++ b/.claude/scripts/resolve-doc-url.sh @@ -1,6 +1,6 @@ #!/bin/bash # Resolve a documentation URL to its source markdown file -# Usage: resolve-doc-url.sh "/path/to/page/" +# Usage: resolve-doc-url.sh "/url/path/" if [ -z "$1" ]; then echo "Usage: resolve-doc-url.sh " diff --git a/CLAUDE.md b/CLAUDE.md index acd302592d0..f8f16033de0 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,7 +81,7 @@ Before creating a new file, use Glob to explore the directory structure and unde * **Headings** – H1 is generated from the front‑matter title. Subsequent headings increment by one level at a time. Don't use bold or italics as a replacement for headings. Use title case. Never start headings with numerals. * **Lists and tables** – Bullet lists use asterisks; ordered lists use numbers followed by a period. If there are more than three data points per item, use a table instead. Use the same syntax and structure for all list items in a given list. Use complete sentences to introduce lists and tables, not partial sentences completed with the list items. * **Indentation** – Four spaces for sub-lists and nested content. Alerts in lists are an exception: don't indent alert lines but do omit preceding blank line. -* **Links** – Use absolute paths starting with a leading slash (`/deployment/`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Section title](/path/to/page#anchor-id)` to link to a heading in another page or `[Section title](#anchor-id)` to link to a heading in the same page). +* **Links** – Link using the target page's `url` front matter field, not its file system path (e.g., `/deployment/` from front matter, not `content/en/docs/deployment/_index.md`). Use descriptive link text such as the page title, not "click here". To link to a heading, add an anchor ID (`{#anchor-id}`) next to the heading and use that ID in the URL (for example, `[Prerequisites](/deployment/mendix-cloud/#prerequisites)` to link to a heading in another page or `[Prerequisites](#prerequisites)` to link to a heading in the same page). * **Images** – Always include `alt` text (or `alt=""` if decorative). Use W3C guidelines. Reference images with the `figure` shortcode. * **Code** – Use fenced code blocks with language specifier. Do not modify text that appears in code formatting (inline backticks or code blocks), even to fix apparent inconsistencies or apply naming conventions. @@ -105,18 +105,18 @@ Call tools in parallel for independent operations (reading multiple files, multi ### Tool Selection +* **Helper Scripts** + * For URL resolution, use `bash .claude/scripts/resolve-doc-url.sh` instead of spawning agents. This resolves documentation URLs (e.g., `/community-tools/contribute-to-mendix-docs/`) to their source Markdown files and ensures Grep uses efficient flags consistently. * **Read** – Use to view specific files you know the path to * **Edit** – Use to modify existing files with targeted changes * **Glob** – Use to find files by pattern (e.g., `*.md`, `**/*config*`) * **Grep** – Use to search file contents for specific text or patterns * **Write** – Use only for creating new files (prefer Edit for existing files) -* **Helper Scripts** – Use `.claude/scripts/resolve-doc-url.sh` to resolve documentation URLs (e.g., `/path/to/page/`) to their source markdown files. This is faster and more token-efficient than using Grep to search front matter. ### Cross-Reference Verification When following or verifying documentation links: -* Use `.claude/scripts/resolve-doc-url.sh "/path/to/page/"` to quickly find the source file for a URL -* This is more efficient than Grep for URL-to-file lookups +* Use `bash .claude/scripts/resolve-doc-url.sh "/url/path/"` to quickly find the source file for a URL When modifying URLs or anchor IDs: 1. Use Grep to search for the old URL/anchor across all documentation files