# \[ANN\] SciCodeNotes 1.0.0—external Markdown notes and LaTeX previews for source code (vsc extension)
**URL:** https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218
**Category:** VS Code
**Tags:** note, vscode, comment
**Created:** [September 5, 2026, 2:22am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218 "2026-09-05T02:22:23Z")
**Posts on this page:** 20
**Page:** 1
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 5, 2026, 2:22am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/1 "2026-09-05T02:22:23Z")
Hi everyone,
I’m happy to announce the first release of **SciCodeNotes** , a VS Code extension for attaching external Markdown notes to precise ranges of source code.
SciCodeNotes was originally designed for scientific computing, where formulas, derivations, assumptions, references, and implementation rationale often need more space than ordinary source comments can provide. However, it is not restricted to scientific code—it can be used with any programming language or source file.
Instead of adding large comment blocks to the source, SciCodeNotes stores notes separately and presents them beside the relevant implementation. LaTeX formulas can be rendered directly in the editor and in rich hover content.
## Demo
The source-side preview can render formulas beside their implementation:
Hovering the preview reveals the complete Markdown note:
## Why external notes
In production code, you usually do not want long explanations, unfinished ideas, internal derivations, or implementation notes exposed as source comments. At the same time, removing that context entirely can make complex code difficult to understand and maintain.
SciCodeNotes provides a sidecar annotation layer for this information. Select a source range and attach a separate Markdown note without modifying the code itself. The note can contain formulas, derivations, references, tables, or anything else supported by Markdown. Its first line appears beside the relevant code, while hovering reveals the complete note with rendered LaTeX.
The attachment follows ordinary code changes whenever possible. Notes can be stored with the repository or in an external location, and portable links can connect related notes and source ranges.
## Install
- [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ShakiraChristian.scicodenotes)
- [Source code on Codeberg](https://codeberg.org/karei/SciCodeNotes)
SciCodeNotes is released under the MIT License. Feedback, bug reports, and suggestions are welcome.
---
### Author:  [@ducksoverip](https://discourse.julialang.org/u/ducksoverip)
#### Post date: [September 5, 2026, 4:58pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/2 "2026-09-05T16:58:00Z")
Hey, this looks super cool, and is definitely something that could fit my use case—I have a number of programs with huge comment blocks explaining my the formula being implemented, where it comes from, stuff I plan to do and so on. That said, I’m curious about what differentiates this from ordinary documentation, since that’s already attached to specific source code, contains Markdown and LaTeX formulas, etc. Is the difference simply that the SciCodeNotes are meant to be more internal? Relatedly, is there a convenient way to convert the notes to more public-facing documentation? It could save a lot of repeated work if you could just clean up and organize your internal notes and turn them into docs, for example.
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 6, 2026, 4:14am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/3 "2026-09-06T04:14:42Z")
Glad you’re interested in this, and that’s a really good point. The way I see it, there are two main differences between ordinary documentation and SciCodeNotes: how private/internal information is handled, and what the information is organized around.
The first difference is privacy and publication.
With ordinary documentation, you could of course organize a project like this:
```plaintext
src/
├── file1.jl
├── file1.md
├── file2.jl
└── file2.md
```
In a typical documentation workflow, though, those Markdown files would usually end up in version control together with the source code, and would therefore be shared or published with the repository. You can certainly add them to `.gitignore`, or keep them somewhere outside the repository, but that is something you have to arrange yourself.
SciCodeNotes treats private sidecar notes as a normal use case. You can keep the notes under `.scicodenotes/` and exclude that directory with `.gitignore`, or store the entire note database outside the repository. This makes it easy to keep internal derivations, unfinished ideas, implementation details, and similar material close to the source code without putting them into the public repository.
The second difference is what the information is organized around.
Ordinary documentation is usually document-centric: you start with a document and then refer to or describe the code from there. If you want to point to a specific piece of implementation, you usually have to record the file, function, or line manually, and that reference normally does not move when the source code changes.
SciCodeNotes is source-code-centric instead: you start with the source code and attach knowledge directly to a precise source range. That attachment is part of the note itself, and SciCodeNotes tries to keep it attached to the corresponding code as the source changes. So, you will be working with the source code.
> [@ducksoverip](#):
>
> Relatedly, is there a convenient way to convert the notes to more public-facing documentation?
In principle, yes. But SciCodeNotes notes may naturally contain things like:
- half-finished derivations
- reasons why a particular approach was rejected
- benchmark observations
- temporary assumptions
- TODOs
Simply concatenating all of those notes would not produce very good public documentation.
On the other hand, if your workflow is more structured–for example, if you carefully maintain one SciCodeNote for each function–then I can definitely imagine exporting them into something closer to Julia’s documentation:
function → explanation → related source location
In that kind of workflow, SciCodeNotes could become an public documentation and reduce the amount of duplicated writing.
I do not yet know what your actual workflow looks like, though. If this is something you would genuinely like to use, I would be very interested in seeing a concrete example of how you imagine organizing and exporting the notes. Please feel free to open an issue in the repository and describe the workflow you have in mind. That would give me a much better basis for designing the feature around a real use case.
---
### Author:  [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)
#### Post date: [September 6, 2026, 3:20pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/4 "2026-09-06T15:20:12Z")
> [@karei](#):
>
> while hovering reveals the complete note with rendered LaTeX.
This looks very useful, thanks.
I am probably doing something wrong as for some reason the VS Code hovering window failed to render the formulas:
(for the formulas to display I need to open the preview window)
> **The full note is provided here.**
>
> ```julia-auto
> # Wyllie Time-Average Equation
>
> Relates sonic transit time to porosity in a fluid-saturated rock, assuming
> a simple mixing law between matrix and fluid travel times.
>
> ## Assumptions
> - Rock is a stack of alternating matrix and fluid layers, sonic wave travels
> through both in series (no bypassing).
> - Only valid for clean, consolidated, fully saturated formations.
> - Breaks down in unconsolidated or gas-bearing zones (velocity underestimated).
>
> ## Formula
>
> $$
> \frac{1}{V} = \frac{\phi}{V_f} + \frac{1 - \phi}{V_{ma}}
> $$
>
> Equivalently, in terms of transit time $\Delta t$ (µs/ft), since $\Delta t = 1/V$:
>
> $$
> \Delta t = \phi \, \Delta t_f + (1 - \phi)\, \Delta t_{ma}
> $$
>
> Solving for porosity:
>
> $$
> \phi = \frac{\Delta t - \Delta t_{ma}}{\Delta t_f - \Delta t_{ma}}
> $$
>
> ## Variables
> | Symbol | Meaning | Typical value |
> |---|---|---|
> | $\Delta t$ | Measured sonic transit time | from log |
> | $\Delta t_{ma}$ | Matrix transit time | 55.5 µs/ft (sandstone) |
> | $\Delta t_f$ | Fluid transit time | 189 µs/ft (freshwater mud) |
> | $\phi$ | Sonic-derived porosity | — |
>
> ## References
> Wyllie, M.R.J., Gregory, A.R., and Gardner, L.W. (1956), "Elastic wave
> velocities in heterogeneous and porous media," *Geophysics*, 21(1), 41–70.
>
> ```
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 6, 2026, 4:09pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/5 "2026-09-06T16:09:45Z")
Hmm… I can’t reproduce this issue on my machine. So I plan to focus on adding debug log output when Mathjax initialization fails in the next version. By then, you’ll know what happened to Mathjax on your machine. I’ll get it done as soon as possible.
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 7, 2026, 1:56am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/6 "2026-09-07T01:56:35Z")
> [@rafael.guerra](#):
>
> I am probably doing something wrong as for some reason the VS Code hovering window failed to render the formulas:
Hi, I just released SciCodeNotes 1.0.1 with improved MathJax diagnostics.
Could you please update to 1.0.1, reload or restart VS Code, reproduce the formula-rendering issue, and then open:
Toggle Panel → Output → SciCodeNotes
If there is any diagnostic output there, could you send it to me? That should help me identify what is failing in your environment.
---
### Author:  [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)
#### Post date: [September 7, 2026, 9:43am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/7 "2026-09-07T09:43:26Z")
Hi karei,
Thanks for the 1.0.1 diagnostics update.
Here’s what showed up in the SciCodeNotes Output channel after reproducing the issue:
> **SciCodeNotes diagnostic**
>
> ```julia-auto
> [2026-09-07T09:26:37.623Z] Math rendering failed.
> Phase: tex2svg
> Formula: inline; length=4; fingerprint=10ce0200b450
> Error type: TypeError
> Error message fingerprint: d03a0f993daf
> Stack:
> at HoverMathRenderer.renderSvg (c:\Users\jrafa\.vscode\extensions\shakirachristian.scicodenotes-1.0.1\out\hoverMath.js:276:34)
> at runNextTicks (node:internal/process/task_queues:65:5)
> at processTimers (node:internal/timers:538:9)
>
> ```
And in case it helps:
> **About VS Code**
>
> ```julia-auto
> Version: 1.136.1 (user setup)
> Commit: a44adf7f53e00964ab890f9f8758a334f1fc15bc
> Date: 2026-09-03T05:06:41Z
> Electron: 42.10.0
> ElectronBuildId: 15109253
> Chromium: 148.0.7778.280
> Node.js: 24.18.1
> V8: 14.8.178.38-electron.0
> @github/copilot: 1.0.81-0
> @github/copilot-sdk: 1.0.11
> OS: Windows_NT x64 10.0.26200
>
> ```
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 7, 2026, 11:36am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/8 "2026-09-07T11:36:32Z")
Hi rafael.guerra,
Thank you for the detailed feedback. I was able to reproduce the issue on a Windows virtual machine, identify the cause, and fix it in SciCodeNotes 1.0.2.
If you would like to know the reason, please read on. Otherwise, you can stop reading here. 😉
> **Details**
>
> The problem turned out to be related to how MathJax 4.1.3 loads its components on Windows.
>
> SciCodeNotes initializes MathJax through its Node API. During initialization, MathJax eventually resolves these components to absolute paths and passes them to its loader.
>
> On Linux, an absolute path such as
>
> `/home/user/.../input/tex.js`
>
> can be passed directly to JavaScript’s dynamic `import()`.
>
> On Windows, however, the equivalent path is something like
>
> `C:/Users/.../input/tex.js`
>
> and Node’s ECMAScript Module (ESM) loader does not accept a Windows absolute filesystem path in that form. It expects a `file://` URL instead, such as
>
> `file:///C:/Users/.../input/tex.js`.
>
> This is closely related to a previous MathJax Windows issue, [MathJax #3481](https://github.com/mathjax/MathJax/issues/3481), which reported the same Node error:
>
> > On Windows, absolute paths must be valid file:// URLs.
>
> MathJax fixed that issue by converting Windows paths to `file://` URLs. There was later another related CommonJS/ESM path-handling issue, [MathJax #3585](https://github.com/mathjax/MathJax/issues/3585), because CommonJS `require()` and ESM `import()` require different path representations on Windows.
>
> In MathJax 4.1.3’s Node loader, there is a problematic combination: the resolved component path could remain a Windows filesystem path such as `C:/...`, while the component loader was still implemented using dynamic `import()`. As a result, component loading failed before MathJax had completed its initialization.
>
> The underlying loading error was not propagated to SciCodeNotes, so it only surfaced later during formula rendering.
>
> In 1.0.2, I changed the MathJax loader so that Windows absolute paths are converted to `file://` URLs before `import()`. Other paths are left as-is. I also verified on the same Windows virtual machine, and math rendering now works normally.
>
> Thanks again for reporting this. It was helpful in tracking the problem down.
---
### Author:  [@rafael.guerra](https://discourse.julialang.org/u/rafael.guerra)
#### Post date: [September 7, 2026, 12:02pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/9 "2026-09-07T12:02:45Z")
Thanks, karei, confirmed that the hover math rendering works correctly now, appreciate the quick turnaround on this!
---
### Author:  [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)
#### Post date: [September 7, 2026, 12:06pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/10 "2026-09-07T12:06:43Z")
Very cool extension.
How fast is the manual latex-\>svg pipeline? If it’s reasonably snappy we should probably put something similar into the Julia extension too (for docstrings), ideally as a factored out JS library.
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 7, 2026, 12:32pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/11 "2026-09-07T12:32:46Z")
Yes, very snappy 😎
I benchmarked the current MathJax 4.1.3 pipeline locally. On Linux/x64 with Node 26.3.1 and an Intel Core i7-10875H, MathJax initialization takes about 110 ms and only happens once. The first render after initialization is about 21 ms, and after warm-up TeX-to-serialized-SVG is roughly 2.1 ms median per formula, with 95% of renders under about 3.1 ms.
If you’d like, I can also factor this out into a small shared JS library.
---
### Author:  [@pfitzseb](https://discourse.julialang.org/u/pfitzseb)
#### Post date: [September 8, 2026, 9:22am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/12 "2026-09-08T09:22:33Z")
> [@karei](#):
>
> If you’d like, I can also factor this out into a small shared JS library.
That would be great, yes!
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 9, 2026, 4:48am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/13 "2026-09-09T04:48:36Z")
I factored out the TeX-to-SVG rendering part you mentioned into a standalone repository: [mathjax-svg](https://github.com/abcdvvvv/mathjax-svg). It has no VS Code dependency and provides the MathJax runtime layer.
The npm package is also published as `mathjax-svg`.
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 9, 2026, 4:52am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/14 "2026-09-09T04:52:51Z")
# Version 1.1.0 is out!
A really cool new feature has been added: you can now attach notes directly to any location within your source code! (No longer limited to faint text at the end of a line.)
Example image
---
### Author:  [@Boris](https://discourse.julialang.org/u/Boris)
#### Post date: [September 11, 2026, 11:02am UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/15 "2026-09-11T11:02:38Z")
Honestly this feels like a game-changer
The times I have realised that I have forgotten how I have defined a variable and that let to bugs down the line is much more than I care to admit. And no, standard documentation does not make it this easy, despite heavily commenting my code.
---
### Author:  [@Boris](https://discourse.julialang.org/u/Boris)
#### Post date: [September 15, 2026, 3:28pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/16 "2026-09-15T15:28:34Z")
I don’t know if this is the place notes did not survive a cut and paste of the code. Should I open an issue on codeberg?
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 15, 2026, 3:38pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/17 "2026-09-15T15:38:51Z")
You mean, after you cut and pasted the code, the comments were lost?
That’s normal, because it’s difficult to make comments track the code itself, and I only did the tracking function to a certain extent.
---
### Author:  [@Boris](https://discourse.julialang.org/u/Boris)
#### Post date: [September 15, 2026, 3:39pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/18 "2026-09-15T15:39:55Z")
Yes, exactly.
---
### Author:  [@karei](https://discourse.julialang.org/u/karei)
#### Post date: [September 15, 2026, 3:41pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/19 "2026-09-15T15:41:27Z")
But your question reminded me. Since you have this need, I will find a way to expand the tracking scope of the comments to the original code.
Could you tell me if it’s convenient, do you often use cross-file cut and paste, or just the same file?
---
### Author:  [@Boris](https://discourse.julialang.org/u/Boris)
#### Post date: [September 15, 2026, 5:00pm UTC](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218/20 "2026-09-15T17:00:34Z")
Thanks for the time!
I would say that I have done both but rarely. What I did in the above case was copy and pasting across files. While I am developing my code, I wrote the notes of what is what and then I decided to move the function to another file for better organization. I would say this is the more likely case than moving functions around in a large file.
[Next page](https://discourse.julialang.org/t/ann-scicodenotes-1-0-0-external-markdown-notes-and-latex-previews-for-source-code-vsc-extension/139218.md?page=2)