doc-link-convention

Doc Link Convention

Owner Agent: Soyo (Reviewer) — flagged at review-time when editing Maigo source. Consumers: any task editing agents/ / commands/ / skills/ in the Maigo repo.

When to apply

Maigo's agents/*.md, commands/*.md, and skills/*/SKILL.md are dual-context:

• They are read raw on GitHub by contributors / claude --plugin-dir.
• They are also pulled into the docs site via docs/{agents,commands,skills}/<name>.md include-markdown shims.

A relative cross-source link works in one view but breaks the other.

The rule

Cross-source link → absolute GitHub URL. No exceptions.

[/maigo:remember](https://github.com/Lee-W/maigo/blob/main/commands/remember.md)

Not:

[/maigo:remember](remember.md)                         <!-- ❌ relative -->
[/maigo:remember](../commands/remember.md)             <!-- ❌ relative -->
[/maigo:remember](/commands/remember.md)               <!-- ❌ root-relative -->

Why a relative link breaks mkdocs build --strict

include-markdown defaults to rewrite-relative-urls=true. When it inlines commands/remember.md into docs/commands/remember.md, it rewrites relative URLs from the destination page's perspective. But the source path (commands/remember.md) differs from the mkdocs page path (docs/commands/remember.md, which is a shim), so the rewrite points at a location mkdocs cannot resolve → Aborted with N warnings in strict mode!.

Absolute URLs are not rewritten by include-markdown, so both the GitHub raw view and the mkdocs page resolve correctly.

Disabling rewrite-relative-urls is also wrong: cross-directory relative links to real reference docs (e.g. ../docs/reference/memory.md) rely on the rewrite to become mkdocs-resolvable.

Exception: links to real reference docs

When the link target is a real doc page under docs/reference/ or docs/guides/ (not a shim), a relative link is correct because rewrite-relative-urls=true will produce the right final URL: