mdvdb backlinks

Show files that link TO a specific file. Unlike mdvdb links, which shows both directions, backlinks focuses on incoming graph connections. A backlink may come from a body Markdown link, a body wikilink, or a whole-value frontmatter Relation.

Usage

mdvdb backlinks <FILE_PATH> [OPTIONS]

Arguments

The FILE_PATH must be the relative path as stored in the index (relative to the project root). The file must have been ingested for its backlinks to be available.

Options

This command has no command-specific options. Only global options apply.

Global Options

These options apply to all commands. See Commands Index for details.

Human-Readable Output

When run without --json, backlinks displays a formatted list of files linking to the target:

  ● Backlinks to docs/api/endpoints.md

  Incoming: 4 incoming links

  ├── docs/architecture.md "API Endpoints"
  │   line 12
  ├── docs/index.md "Endpoints Reference"
  │   line 34
  ├── docs/api/overview.md "Endpoints" [wikilink]
  │   line 8
  └── projects/relaunch.md "API Endpoints" (reference)
      frontmatter

If no files link to the target:

  ● Backlinks to docs/orphan-page.md

  ✗ No files link to docs/orphan-page.md

Output Elements

Examples

# Show backlinks for a file
mdvdb backlinks docs/api/endpoints.md

# Show backlinks as JSON
mdvdb backlinks docs/api/endpoints.md --json

# Show backlinks for a file in a specific project
mdvdb backlinks notes/meeting.md --root /path/to/project

# Show backlinks with debug logging
mdvdb backlinks docs/readme.md -vv

JSON Output

BacklinksOutput (--json)

{
  "file": "docs/api/endpoints.md",
  "backlinks": [
    {
      "entry": {
        "source": "docs/architecture.md",
        "target": "docs/api/endpoints.md",
        "text": "API Endpoints",
        "line_number": 12,
        "is_wikilink": false,
        "field": null
      },
      "state": "Valid"
    },
    {
      "entry": {
        "source": "docs/index.md",
        "target": "docs/api/endpoints.md",
        "text": "Endpoints Reference",
        "line_number": 34,
        "is_wikilink": false,
        "field": null
      },
      "state": "Valid"
    },
    {
      "entry": {
        "source": "docs/api/overview.md",
        "target": "docs/api/endpoints.md",
        "text": "Endpoints",
        "line_number": 8,
        "is_wikilink": true,
        "field": null
      },
      "state": "Valid"
    },
    {
      "entry": {
        "source": "projects/relaunch.md",
        "target": "docs/api/endpoints.md",
        "text": "API Endpoints",
        "line_number": 0,
        "is_wikilink": false,
        "field": "reference"
      },
      "state": "Valid"
    }
  ],
  "total_backlinks": 4
}

BacklinksOutput Fields

ResolvedLink Fields

LinkEntry Fields

Backlinks vs Links

Use mdvdb backlinks when you want a focused answer to “who links to this file?” without the outgoing link information. Use mdvdb links when you need the full bidirectional picture or want multi-hop traversal.

Notes

• The backlinks command opens the index in read-only mode. It never modifies the index.
• Backlinks are computed from the link graph built during ingestion. Run mdvdb ingest to populate the link graph.
• Body Markdown links and wikilinks are tracked, as are whole-value link-shaped strings and string-list elements in frontmatter. Relation entries identify their originating field.
• Body link targets are resolved relative to the source file’s directory, so [text](../api/endpoints.md) in docs/guides/setup.md resolves to docs/api/endpoints.md. Relation targets use the collection-root, overlay target:, and source-directory rules in Relations.
• The backlinks array contains ResolvedLink objects (with an entry and state field), the same type used in the outgoing array of mdvdb links.
• For multi-hop backlink traversal (e.g., “what links to the files that link to this file?”), use mdvdb links --depth 2 which includes both outgoing and incoming multi-hop trees.

Related Commands

• mdvdb links — Show both outgoing and incoming links with optional multi-hop depth
• mdvdb orphans — Find files with no links at all (no outgoing or incoming)
• mdvdb edges — Show semantic edges between linked files
• mdvdb graph — Visualization-ready graph data (nodes and edges)
• mdvdb get — Get metadata for a specific file
• mdvdb search — Search with --boost-links for link-aware scoring

See Also

• Link Graph — How mdvdb extracts links, builds the graph, computes backlinks, and detects orphans
• JSON Output Reference — Complete JSON schema reference for all commands
• Configuration — Link-related config vars (MDVDB_SEARCH_BOOST_LINKS, MDVDB_SEARCH_BOOST_HOPS)