Markdown Links Not Working? Check Paths and Headings

Find the smallest failing example

A relative link starts at the current document folder. A root-relative link starts at the website root. Neither automatically means the root of every repository or documentation project. Inspect the rendered destination and its final response after redirects.

[Setup guide](./docs/setup.md)

[Installation section](#installation)

Check the destination behavior

Heading fragments depend on how a renderer generates IDs. Renaming a heading, duplicate headings and punctuation can change those fragments. Copy the actual heading link when possible. For URLs containing spaces or parentheses, use supported escaping or angle-bracket destination syntax and test the full address.

A repeatable debugging sequence

1. Save the failing source before editing it.
2. Remove surrounding content until a few lines reproduce the symptom.
3. Compare that sample with the destination documentation.
4. Change one thing at a time and check both source and output.
5. Restore the surrounding document and inspect the delivered version.

This separates syntax errors from missing renderer features and inaccessible files. An example that works in one preview can still fail in the final publishing workflow.

Keep the repair portable

Record any required renderer extensions beside the example. Keep essential meaning in ordinary paragraphs and retain the editable original. Check links, assets and formatting after moving the file. Previewing locally helps diagnose the source; the final check belongs where people will actually read it.

When a preview tool helps

A side-by-side preview makes small source changes easier to inspect. Markups is one option for trying the example, but its renderer settings can differ from the publishing destination. Compare the destination output before considering the problem solved.