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.

Install SciCodeNotes from the Visual Studio Marketplace.

Quick start

1. Select a line or range of code, then right-click and choose Add Note (or press Ctrl+/ on Windows/Linux or Cmd+/ on macOS).
2. Write your note in the Markdown editor and save it.
3. Switch back to the source file. The first line of the note now appears next to the selected code.
4. Hover over the note to read it in full or choose Edit, Preview, or More.

If the first line contains inline TeX, or the note begins with a display-math block, SciCodeNotes shows the rendered formula instead of a plain-text preview:

Hover over the preview to see the complete note:

To attach a note to an exact character range, select the text and choose Add Note to Selection (Ctrl+Shift+/, or Cmd+Shift+/ on macOS). The note will decorate the selected text instead of appearing at the end of the line. Range notes can overlap or nest, but two notes cannot occupy exactly the same range.

Set Color overrides the default source-side color for an individual note, changing the text color of a line-end preview or the border and underline of a range note. Set Background Color changes the background in either style. Both menus include common preset colors and a Custom... option for hexadecimal colors.

Notes are stored outside the source file in notes.json. To browse and manage notes across the project, open SciCodeNotes Manager in the NOTES panel.

Links

SciCodeNotes links can point to another note by its stable ID or to a fixed range of code:

• To link to a note, right-click it in SciCodeNotes Manager and choose Copy Link to SciCodeNote.
• To link to a fixed range of code, select it in the source editor and choose Copy SciCodeNotes Link to Selection.

Following code changes

A SciCodeNote tracks the selected code rather than a fixed line number, so it follows normal edits automatically. If the file changes while VS Code is closed—for example, after switching branches—or the code is substantially reorganized, SciCodeNotes searches for the original code in the new version. Copying code also copies resolved notes fully contained in the selection; pasting creates independent notes, while an exact Cut/Paste moves the original notes. Clipboard-history recovery is supported for uniquely matching text within the same VS Code window, and each recovered entry is consumed once.

If SciCodeNotes cannot find a safe match, the note becomes unresolved but 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.

Reattaching the note updates its anchor and clears the unresolved state. Deleting a source file does not delete its SciCodeNotes.

Storage

Each workspace folder has its own storage location, so folders in the same multi-root VS Code window can use different policies:

• Repository Storage keeps that folder's notes in .scicodenotes/notes.json. SciCodeNotes detects an existing repository store independently for each workspace folder. You can commit .scicodenotes/ or add it to .gitignore.
• External Storage lets that folder use an existing notes.json file or a directory outside the repository, such as a synchronized folder. SciCodeNotes reads the file at startup, when you run Refresh, and before it saves. Non-conflicting changes are merged automatically; if two changes conflict, SciCodeNotes asks you what to keep. If the file is temporarily unavailable, the other workspace folders continue to work and the affected scope keeps its current notes in memory.

SciCodeNotes Manager groups notes by workspace folder when multiple scopes are open and combines their unresolved count in the panel badge. Files opened outside every workspace folder can use a separate external-only Loose Files store.

If no storage location has been detected or configured for a source scope, SciCodeNotes asks you to choose one when you first create or move a note into that scope.

Settings

Change these options in VS Code Settings or add them to settings.json.

Rendering behavior. Plain-text previews are limited to 80 characters. By default, a math preview that is taller than the editor line is scaled down to fit. If that would shrink it below 90% of its original size, SciCodeNotes shows a plain-text preview instead. Enable sciCodeNotes.allowMathProjectionOverflow to keep math at its original size, even when it extends beyond the line.

Storage is configured separately through SciCodeNotes: Configure Storage.

Keybindings

You can change or remove these keybindings in VS Code Keyboard Shortcuts.

Why SciCodeNotes

Code comments work well for short explanations, but long derivations, assumptions, and references can quickly get in the way. Moving that material into a notebook keeps the source clean, but separates the explanation from the implementation.

SciCodeNotes keeps the full Markdown note outside the source file and shows a preview in plain text or rendered math beside the relevant code. Hover over the preview to read the complete note. This keeps the reasoning close to the implementation without changing the code itself.

License

MIT License