Skip to content
contextlint

GRP-003 Orphan documents

Overview

Section titled “Overview”

Among the documents matched by files, detects files that no other document links to (zero incoming references). Detected files are reported as warning. This is a project-scope rule and is evaluated across all documents loaded via include.

Files listed in entryPoints (entry-point documents like READMEs and indexes that are reached from outside) are not treated as orphans.

Why it matters

Section titled “Why it matters”

Renaming a file, moving it to another directory, or creating a new file without linking it from any existing document all create “orphan documents” — files that exist but cannot be reached. These are invisible without explicit search, so no one ends up reading them, and no one notices when their content goes stale. Bulk AI-generated documents are especially prone to this. This rule detects orphans.

Options

Section titled “Options”
FieldTypeRequiredDescription
filesstring—Glob of files considered for orphan detection. If omitted, every document is considered
entryPointsstring[]—Array of globs treated as entry points and excluded from orphan detection

Each pattern in entryPoints is matched both against the full path and against the basename of each file. README.md (basename) and docs/README.md (full path) both work.

Bad example

Section titled “Bad example”

Suppose the repository contains these three files:

docs/README.md       — entry-point document
docs/architecture.md — referenced from README via [ ](./architecture.md)
docs/legacy-notes.md — not linked from anywhere

docs/legacy-notes.md is not referenced by any other document, which triggers a violation.

docs/legacy-notes.md
  line 1  warning  docs/legacy-notes.md has no incoming references from any other document  GRP-003

After fix

Section titled “After fix”

Add a link from a referencing document, or remove the file if it is no longer needed.

docs/architecture.md:


## Background


For historical context, see [legacy notes](./legacy-notes.md).

Configuration example

Section titled “Configuration example”
{
  "rule": "grp003",
  "options": {
    "files": "docs/**/*.md",
    "entryPoints": ["README.md", "docs/index.md"]
  }
}

List under entryPoints files that are legitimately unreferenced because they serve as entry points. Forgetting to do so will cause the README itself to be flagged as an orphan, so make a habit of always adding table-of-contents and landing-page files to entryPoints.

Section titled “Related rules”