TopolearnLong docs with many links stay editable when URLs live in one place instead of inside every sentence.
Reference-style links separate the link from its URL:
Read the [style guide][guide] and the [API docs][].
[guide]: https://example.com/style "Style guide"
[API docs]: https://example.com/api[text][label]uses the definition with that label; labels are case-insensitive.[text][](collapsed) and[text](shortcut) use the text itself as the label.- Definitions
[label]: url "optional title"can appear anywhere and render as nothing; put them at the end of a section or file. - The same works for images:
![logo][logo-img].
Benefits: paragraphs read like prose, a URL used five times is defined once, and changing it is one edit. If a label has no definition, the brackets are left as literal text, which makes typos easy to spot.
Heading anchors aren't standard Markdown; each renderer generates IDs. GitHub lower-cases the text, removes punctuation except hyphens and underscores, replaces spaces with hyphens and appends -1, -2 for duplicates. Other tools (MkDocs, Docusaurus, Hugo) use similar but not identical rules, and some support explicit IDs such as ## Install {#install}. For links that must stay stable across renderers and heading edits, add an explicit anchor with HTML: <a id="install"></a>.
Example
Our [contributing guide][contrib] explains the workflow. Questions go to
the [forum], and bugs to the [issue tracker][issues].
![Logo][logo]
See [Error handling](#error-handling) and [FAQ: Why?](#faq-why).
## Error handling
## FAQ: Why?
[contrib]: CONTRIBUTING.md
[forum]: https://forum.example.com "Community forum"
[issues]: https://github.com/example/project/issues
[logo]: docs/logo.svgRemember
- [text][label] plus [label]: url keeps URLs out of the prose
- Labels are case-insensitive; [text] alone uses the text as label
- Heading anchor rules differ per renderer; use explicit anchors when stability matters
Watch out for
- Linking to #FAQ-Why? on GitHub; the generated anchor is lower case without punctuation: #faq-why.