CodePort — Navigate Markdown to Source Code

简体中文 · English

Put the cursor on a name written in your Markdown and jump to its source. CodePort brings go-to-definition, Peek, Find All References and hover to fenced code blocks and inline code, plus clickable path/file.c:42 links — backed by a CodeGraph index.

Quick start

1. Install the extension. Package it once, then install what it produced (or pick the same file with Extensions → … → Install from VSIX…):

npm install && npm run package
code --install-extension codeport-*.vsix

2. Index your project once. CodePort reads a CodeGraph index; it never builds one.

npm i -g @colbymchenry/codegraph --registry=https://registry.npmjs.org
cd <your-project> && codegraph index

Use the official npm registry. Mirrors such as npmmirror do not carry CodeGraph's platform package, and npm reports the unfetchable optional dependency as success — the install looks fine and fails on first use.

3. Jump. Open a note in that project, put the cursor on a name inside a code block or inline code, and press F12 (or Ctrl+Click).

What you can do

That last one rewrites `nx_start()` into [nx_start()](https://github.com/rongbc/codeport/blob/HEAD/../sched/init/nx_start.c#L123).

A note, and what happens in it

# Scheduler

Call `nx_start()` to initialise the scheduler; it is declared in `include/nx/sched.h:42`.

```c
nxsched_add_readytorun(tcb);
```

• nx_start and nxsched_add_readytorun jump to their definitions.
• include/nx/sched.h:42 opens that file at line 42.
• Hovering any of them says why that definition was picked.

A name with several definitions opens the usual Peek list. In C/C++ projects that have a compile_commands.json, that list can narrow to the one definition the build actually compiles.

Path links

Any file type, and a link appears only when the target exists.

`/home/me/proj/src/main.c:42`   absolute — opens at line 42
`src/main.c:42`                 relative — search paths, workspace root, then the note's own folder
`docs/diagram.svg`              images, JSON, Markdown — anything
`src/Makefile`                  no extension, still a path

Notes that live outside the code tree can add their own bases with codeport.codeLink.searchPaths. Path links never touch the graph, so they work even without CodeGraph.

Settings

Where CodeGraph lives is deliberately not a setting: install it and it is found on PATH. What goes into the index — files, languages, ignores — is CodeGraph's own codegraph.json.

Requirements

• VS Code 1.90 or newer.
• CodeGraph installed and the project indexed (codegraph index). Without it, path links still work but symbol navigation reports "no definition found".
• A folder open in the window. The note itself may live elsewhere: a file opened by a path outside the folder (say, through a symlink) still resolves against the window's folder.

Commands

CodePort: Go to Definition · CodePort: Peek Definition · CodePort: Find All References · CodePort: Insert Source Link · CodePort: Show Log · CodePort: Show Index Statistics · CodePort: Show Index Rebuild Command

What it won't do

• Macros. #define names are not in the graph, so a SOME_MACRO mention will not resolve.
• Prose. Only fenced code blocks and inline code are scanned; a name in a sentence is left alone.
• Compiler-grade semantics. Overloads, templates and #ifdef branches are matched by name and import, so an ambiguous name can pick the wrong candidate — hover shows the evidence it used.
• Links inside fenced code. Markdown does not render them, so Insert Source Link is inline-code only.

Troubleshooting

More

• CodeGraph — the graph engine CodePort reads
• Architecture — how a mention becomes a jump, and the capability boundary
• Changelog · Issues

Development

npm install → npm run check (typecheck, build, tests) · npm run package writes codeport-*.vsix · F5 launches an Extension Development Host. Design notes: docs/ARCHITECTURE.md.

MIT — see LICENSE.