Link to another file that goes nowhere

cross-doc-broken-linkon by defaultJapanese / English

A link to another of the files checked whose file or heading is not there

Example

Flagged

# Guide Before you start, read [Setup](./a.md#preparation).

What chaff prints

3:24 The link "[Setup](./a.md#preparation)" points to "./a.md#preparation", but that file has no such heading

Fixed

# Guide Before you start, read [Setup](./a.md#setup).

What chaff prints

no finding

The file checked together with it (a.md). The flagged and the fixed text are each compared with it

# Steps ## Setup Gather the tools.

How to fix

Match the file's current name and the heading as it is now written. If the file or the heading is gone, remove the link or point it at the page that replaced it.

Why it matters

A manual or a bundle of documents links its pages to each other with relative paths ("[Fees](./pricing.md#monthly-fee)"). Renaming a file or rewording a heading leaves the links from other pages with nowhere to go, and no single file shows it. The files given together are checked against each other: a link whose file is not there, and a link to a heading that file does not have, are pointed out. Heading anchors are compared on letters and digits only.

What it does not flag

URLs, paths from the site's root ("/guide/"), links within the same page (broken-link checks those) and links to files that are not Markdown (images, scripts) are not checked. A missing file in a folder that none of the files checked are in, and a link to a folder ("./guide/"), cannot be confirmed and are not reported. A link without an extension ("./reference") is looked up as .md and the like.

Turning it off or relaxing it

Silence this one spot (in the document)

Relax it for the team (the reason is kept as a comment in chaff.yaml)

npx chaffjs relax cross-doc-broken-link --why "reason"

Turn it off for the team (chaff.yaml)

rules: cross-doc-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, documents

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).

strict	error
normal	warning
relaxed	info

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}" points to "{target}", which is not among the files checked

The link "{link}" points to "{target}", but that file has no such heading

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