LinkFile

A VSCode extension that lets you put the same @link:<id> marker in code and in Markdown docs, and then Ctrl+click (or Cmd+click on macOS) jumps between them. Designed for linking design docs to their implementation (and back).

How it works

LinkFile scans your workspace for a configurable keyword (default @link:) followed by an ID, builds a bidirectional index, and exposes each occurrence as a clickable link, hover preview, and command target.

            ┌──────────────────────────┐           ┌─────────────────────────────┐
            │  src/auth.ts             │           │  docs/design/auth.md        │
            │                          │  shared   │                             │
            │  // @link:auth-flow      │<────────->│  <!-- @link:auth-flow -->   │
            │  export function login() │    ID     │                             │
            │                          │           │  ## 登录流程                │
            └──────────────────────────┘           └─────────────────────────────┘

• Code → Doc: Ctrl+click @link:auth-flow in auth.ts opens the matching doc anchor.
• Doc → Code: Ctrl+click @link:auth-flow in auth.md. If multiple code locations declare the same ID, a Quick Pick lets you choose.
• Hover: see a preview of the other side without leaving the current file.

Features

• Bidirectional Ctrl+click navigation between code and Markdown docs
• Shared-ID model — any file that contains @link:<id> joins the link
• Auto Quick Pick when an ID has multiple targets on the other side
• Hover preview showing the linked file, line number, and the first few lines
• Commands: Go to Linked, Show References, Insert Anchor, Rebuild Index
• Status bar item showing the current number of indexed IDs
• Live updates while you type (debounced) and via a file system watcher
• Configurable: keyword, ID pattern, doc/code/exclude globs, preview size
• Works with any language: the anchor is detected by raw text, independent of comment syntax

Usage example

Put anchors on both sides using the same ID.

src/payments/checkout.ts:

// @link:payment-flow
export async function checkout(cart: Cart) {
  // ...
}

docs/design/payments.md:

<!-- @link:payment-flow -->

## Checkout flow

The checkout endpoint performs the following steps ...

Now:

• In checkout.ts, Ctrl+click @link:payment-flow → jumps to the doc anchor.
• In payments.md, Ctrl+click @link:payment-flow → jumps to the code anchor (or shows a Quick Pick if you have multiple).
• Hover either anchor to see a preview of the linked location.
• Press Ctrl+Alt+L (or Cmd+Alt+L on macOS) on an anchor for the same effect without clicking.

Commands

Configuration

All settings live under linkFile.*:

Changing any linkFile.* setting triggers an automatic re-index.

Build & debug

Requires Node 18+ and VSCode 1.85+.

npm install          # install dev dependencies
npm run compile      # one-shot build → dist/extension.js
npm run watch        # esbuild in watch mode
npm run typecheck    # tsc --noEmit

To launch a debug instance:

1. Open this folder in VSCode.
2. Press F5 (runs the Run Extension launch configuration).
3. A new Extension Development Host window opens with LinkFile loaded.
4. Open a folder that contains some .ts / .md files with @link:... anchors and try Ctrl+click.

Packaging

npx @vscode/vsce package

Produces a .vsix you can install with code --install-extension linkfile-0.1.0.vsix or via the Extensions view → ... → Install from VSIX.

Limitations (by design, for now)

• Clicks inside the Markdown preview are not yet supported. Preview is a sandboxed webview and requires a separate markdown.markdownItPlugins integration; planned for a future release.
• Cross-workspace and cross-repo links are not followed.
• There is no automated rename refactor for IDs yet — rename via workspace-wide find & replace.

License

MIT