All rules

Link that goes nowhere

broken-linkon by defaultJapanese / English

A link that goes nowhere: no address, a missing heading, or no definition

Example

Flagged
## Setup Gather the tools. See [Install](#install) for more.
What chaff prints
3:23 The link "[Install](#install)" points to "#install", which is not a heading on this page
Fixed
## Setup Gather the tools. See [Setup](#setup) for more.
What chaff prints
no finding

How to fix

Fill in the destination. For a heading, match the heading as it is now written. For a reference-style link, add a "[label]: URL" line somewhere in the document.

Why it matters

A link that does nothing when clicked tells the reader something is missing. Three kinds are checked. A link with an empty destination ("[report]()"); a link to a heading on the same page that the page does not have ("[Setup](#setup)" after the heading was renamed or removed); and a reference-style link whose label is never defined ("[report][1]" with no "[1]:" line), which is shown as plain brackets. Renderers build heading anchors differently, so only letters and digits are compared; case, spaces and punctuation do not matter. Brackets holding only numbers ("[1][2]") are citation numbers and are not counted (markdownlint's MD042, MD051 and MD052).

What it does not flag

Heading anchors are compared on letters and digits only, ignoring case and punctuation. Citation numbers ("[1][2]"), subscripts ("A[i][j]"), definitions no link uses and an image reference with its label left out ("![Complete][]", a status icon the site defines) are not reported.

Turning it off or relaxing it

Silence this one spot (in the document)
<!-- stet: broken-link — reason -->
Relax it for the team (the reason is kept as a comment in chaff.yaml)
npx chaffjs relax broken-link --why "reason"
Turn it off for the team (chaff.yaml)
rules: broken-link: off
Technical details
Layer
L1
Status
stable
Severity
warning
Languages
Japanese and English
Suited to
business, technical, blog, legal, docs, academic, literature, speech
Reads from the document
markdown

Levels

Set a level for this rule under rules in chaff.yaml. With nothing set, it runs at the level its genre gives it (see By genre below).

stricterror
normalwarning
relaxedinfo

This rule has no limit to count to. A level sets how a finding is marked: relaxed keeps the finding and marks it a step lower.

By genre

Runs by default in
technical/spec, technical/readme, blog/tech, blog/essay, blog/owned-media, business/proposal, business/report, business/email, business/press-release, business/meeting-notes, legal/contract, legal/statute, legal/judgment, legal/patent, docs/manual, docs/faq, docs/glossary, academic/paper, literature/fiction, literature/essay, literature/poetry, literature/play, speech/address, speech/transcript

Genres

Message

The link "{link}" goes nowhere

The link "{link}" has an empty destination

The link "{link}" points to "{target}", which is not a heading on this page

"{link}" is a reference-style link with no definition (it shows as plain text)

This page is built from the rule's definition file:packages/chaff/rules/broken-link.yaml