SciCodeNotes

SciCodeNotes is a VS Code extension that attaches external notes to code and renders LaTeX formulas in the editor. It brings formulas, derivations, assumptions, references, and implementation rationale next to production code without moving that code into notebooks or bloating source comments.

Quick start

1. Select one line or a continuous range of code.
2. Right click and select Add SciCodeNote (or use shotcut Ctrl+/).
3. Write the note in the Markdown editor and save normally.
4. Return to the source file. A plain-text first line appears beside the bound code. If the first line contains inline TeX, or the note starts with a display-math block, SciCodeNotes renders the Latex formular as an SVG. Enable sciCodeNotes.allowMathProjectionOverflow to allow math previews to exceed the editor line height.
5. Hover the source decoration to read the complete note and use Edit, Preview, or More.

Rendered formulas appear beside their implementation:

Hovering the preview reveals its complete note:

The note body is stored outside the source file in notes.json. Project-wide note management is available through SciCodeNotes Manager in the NOTES Panel.

Links

SciCodeNotes supports portable links:

• Copy Link to SciCodeNote creates a link to another SciCodeNote by its stable ID.
• Copy SciCodeNotes Link to Selection creates a link to a fixed source-file range.

Use the commands rather than constructing links manually.

Following code changes

A SciCodeNote is anchored to the selected code range rather than a line number, and normal edits are tracked automatically. When a file changes while VS Code is closed, moves between branches, or is substantially reorganized, SciCodeNotes attempts to find the original code again.

If it cannot determine the location safely, the note becomes unresolved and remains available and editable. To reattach it:

1. Expand unresolved in SciCodeNotes Manager.
2. Select the new source-code range in the editor. For a whole-line attachment, place the cursor on a non-empty line.
3. Right-click the unresolved note and choose Reattach to Selection.

Reattachment updates the anchor and clears the unresolved state. Deleting a source file does not delete its SciCodeNotes. Each source line can have at most one attached SciCodeNote; for multi-line selections, it occupies the last selected line.

Storage

Each workspace uses one storage location:

• Repository Storage uses .scicodenotes/notes.json in a single-folder workspace and is detected automatically. You can commit or ignore .scicodenotes/; SciCodeNotes does not modify .gitignore. Otherwise, creating the first SciCodeNote asks you to choose a location.
• External Storage uses an existing notes.json file or a chosen directory, such as a synchronized folder. SciCodeNotes reads it at startup, on Refresh, and before saving; it merges non-conflicting changes and asks you to resolve conflicts. If the file is temporarily unavailable, it keeps the current in-memory notes.

Settings

Set it through VS Code Settings, or add it to settings.json.

Rendering behavior. Plain-text previews are capped at 80 characters. With overflow disabled, a math preview taller than the editor line is scaled down to fit. If doing so requires a scale below 0.9, SciCodeNotes uses the same plain-text previews instead. Enable sciCodeNotes.allowMathProjectionOverflow to render math previews of any height.

Storage location is selected through SciCodeNotes: Configure Storage; it is not a VS Code setting.

Keybindings

You can change or remove this keybinding in VS Code Keyboard Shortcuts.

Why SciCodeNotes

SciCodeNotes fills the gap between sidecar code annotations and source-level math preview. Annotation tools can keep rich notes outside source files, while math-hover tools can render TeX written inside source comments. SciCodeNotes combines both ideas: select a source range, bind it to an external Markdown note, and project that note back onto the source editor without modifying the code.

A SciCodeNote can contain derivations, equations, assumptions, modeling rationale, references, tables, and other technical material. TeX in the external note is rendered directly in source hover, so mathematical knowledge remains close to the implementation while the full Markdown document remains separate.

The core workflow is:

selected source range
        ↓
stable SciCodeNote anchor
        ↓
external Markdown note
        ↓
source decoration + rich hover, including rendered TeX

License

MIT License