Update Claude's link guidance#11117
Conversation
|
You've modified Claude Code configuration files. These files contain the shared configuration for all contributors. Please revert this change if unintended. ONLY modify these files if you need to change shared configurations that apply to everyone and have discussed this change with the TW team. To override the Claude settings locally, use For example, if you're changing AWS_PROFILE: Create or edit {
"env": {
"AWS_PROFILE": "your-sandbox-name"
}
} |
| * **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). |
There was a problem hiding this comment.
I opened this PR mostly to clarify this point—Claude was updating URLs for moved files based on the directory structure, not the url front matter.
| ### 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. |
There was a problem hiding this comment.
I updated the wording here for a few reasons:
- The helper script wasn't getting picked up consistently in my tests, so I gave it clear directions to use this script instead of agents, and moved it to the top of the tool selection section.
- The helper script kept failing on its first attempt, so I added "bash" to the command.
- The helper script is actually a grep wrapper—so it does still use grep to search front matter, just in a specific way.
- /path/to/page might imply that the link is based on the directory structure, so I updated it to /url/path/ (or specific examples) to prevent confusion.
MarkvanMents
left a comment
MarkvanMents
left a comment
There was a problem hiding this comment.
Looks good.
Did it perform better in your tests, or does it still miss it sometimes?
Definitely worth merging.
Thanks.
|
Thanks! I definitely can't promise 100% compliance, but I did see improvement. |
2 participants
No description provided.