This article is about my VS Code Extension. Also Github repo.
We've probably all gotten used to it...
Writing Markdown on the left side of VS Code, then glancing over to the right to check the rendered result. And it never quite lines up!
The maddening math symbols. Writing an article on math or physics means embedding formulas in every paragraph. \mathcal{L} for the Lagrangian, \boldsymbol{\theta} for the parameter vector, \partial for the partial derivative. Every single one typed out in full. You've tried memorizing shortcuts, or keeping another file open for frequently-used snippets, or even scrolling all the way up to copy-paste a formula and then editing it.
Every extra LaTeX formula adds another layer of friction. Something that should take two or three sentences ends up sending your mouse and eyes back and forth four or five times.
Have you ever asked yourself: Why do I keep having to let go of the keyboard, reach for the mouse, and hunt through the text, when all I want to do is simply typing? Every one of these actions breaks my thought!
You may say: Just switch tools. There are plenty of Markdown editors out there, some with pretty advanced features.
But, my friend, isn't VS Code a text editor? Why on earth can't I edit a text in a TEXT EDITOR!
The prize pool keeps stacking up...
If you also like using MyST, then congratulations. The Python code in your {code-cell} blocks actually runs, and your readers get to see the beautiful outputs.
But what about you? Can you see them? All you see while typing is Markdown. You either trust that your codes, or secretly write up a .py file somewhere else to test it.
You may say: Why not just use Jupyter Notebook? It natively blends code with Markdown output.
But have you ever opened a .ipynb git diff? It's an entire JSON structure nesting base64-encoded output blobs. A two-line code change produces a mountain of diff. Merge conflicts? Best wishes.
Plus, it's heavy!
You just want to write an article — why do you have to suffer so much? Just because it's always been this way, does that make it the right way?
There Are Not Four Problems — It's One
These four pain points seem scattered — split panes, formulas, code output, format bloat.
But they all point to the same root cause: We've separated "writing" from "seeing."
So why not make it what you write is what you see, and what you see is what you saved?
Every character you type on the keyboard transforms in-place into its final form the moment your focus leaves it. No second pane, no build step, no JSON wrapping. Your .md file stays a .md file — it is its own notebook.
I've always wanted this. I couldn't find it anywhere, and at one point it even dampened my own enthusiasm for writing.
So, I built one!
And So, MyST Notebook
MyST Notebook is a VS Code extension. What it does is simple: it turns .md files into a native notebook editor experience inside VS Code.
The core insight comes down to one sentence: since VS Code 1.85, the notebook editor API has matured enough to support custom notebook types. No need to invent a new editor, no Electron wrappers — the editor you're already using is the best host.
Let's revisit those pain points one by one:
Preview Pane → Inline Rendering
In MyST Notebook, there is no concept of "preview." You write a paragraph, press Enter to jump to the next cell, and the paragraph you just wrote renders in place. Headings, bold, links, lists, blockquotes — all visible in real time.
Your eyes no longer dart left and right. Your screen no longer splits in half. What you see is what your readers will ultimately see.
An honest note: MyST colon fence directives (
:::{note},:::{warning}, etc.) cannot yet be rendered inline in the editor — this is an architectural limitation of the VS Code notebook renderer'smd.renderInline(), and there's no way around it for now. While editing, they appear as plain text;jupyter-book buildwill handle the final output correctly. This is the one compromise in v0.1 that bothers me the most, and I'll keep exploring solutions in future versions. If any fellow devs have good ideas, feel free to reach out anytime.
LaTeX Hell → Math Panel + Autocomplete
\mathcal takes just four keystrokes. Even more commonly, Ctrl+Shift+M opens the math symbol panel — recently used symbols appear at the top, one click to insert.
Also, if you want (like me personally), the whole interaction can be done with keyboard only.
And if you prefer the mouse, the Math Palette sidebar keeps every symbol you've ever typed, ready to click.
This feature is actually tiny, just a handful of lines of code. But it saves you dozens of "type out the same LaTeX command" actions every single day. The flow of writing is built on eliminating these micro-frictions.
Can't See Python Output → Inline Code Execution
Ctrl+Shift+E toggles the current cell into a {code-cell}, Shift+Enter runs it. (You can also use MyST: Insert Executable Cell from the command palette to insert a new one.) MyST Notebook manages the Jupyter kernel itself — no need to install the Jupyter extension, no need to start a server separately. It automatically discovers your Python environment, auto-installs ipykernel and jupyter-server (if they're missing), and streams the output below the cell in real time.
The code you write shows you the result immediately. No build step, no "going backstage."
Kernel died? It auto-restarts on the next run. Want to switch Python environments? Bring up MyST: Reinstall Runtime from the command palette and pick again. Need to send SIGINT to a runaway loop? MyST: Interrupt Kernel.
That's it. Write code, run code, see output. You focus on content, not environment.
Too Heavy → Plain .md
MyST Notebook doesn't create a new file format. Your article is just a plain .md file, sitting quietly in docs/blog/posts/, perfectly compatible with jupyter-book build.
From Git's perspective, it's plain text. Fix a typo, and the diff shows only that one changed line. Two people editing different paragraphs in the same file? A normal merge, not JSON hell.
And in the age of AI, plain Markdown is naturally agent-friendly too.
Your writing output is forever-readable, forever-portable plain text. The extension is just a view — close it, and your article is still complete.
The Following Is Not a Promo — This Is My Own Tool
There are a few features I didn't originally plan to build, but added after using it myself for a week, because I kept noticing "something's missing here":
Auto-split. Press Enter after finishing a paragraph, and a new cell is automatically created with the cursor in place. No clicking an "add cell" button with the mouse, no memorizing shortcuts — just like pressing Enter for a new line. This is the feature that most impacts writing rhythm, yet it sounds the most trivial when you say it out loud.
Knowledge graph. Ctrl+Shift+G opens a D3 force-directed graph showing all [[wikilinks]] and {cite} references and backlinks in the current file. It was originally meant for navigating between notes, but I later discovered — when writing a book, using it to see the relationships between chapters is far more intuitive than hunting through the file tree.
Zotero citations. Because I need to cite papers when I write. One command to configure, then Alt+Shift+Z brings up the reference picker — select one and it inserts {cite}. WSL2 users need a bit of extra network configuration; it's documented.
Shorthand fences. In a prose cell, type runthen Enter, and it auto-expands into a{code-cell}code block. Typeshow and it expands into a display-only code block. Once muscle memory kicks in, it's faster than shortcuts.
Tools Should Fade Into the Background
I wrote this entire article with this extension open. Not as a demo — I was genuinely using it.
In the past, writing a three-thousand-word article meant my gaze would sweep back and forth between the left and right panes hundreds of times. I'd keep a separate "LaTeX common symbols.md" file open for copy-paste. I'd write a code block and then either comment it out or trust it, waiting for jupyter book build to finish before verifying.
Today, I never switched panes once.
Not because this article is simple — quite the opposite. I was writing this while preparing the extension for release, constantly switching between prose and code. But that switching happened at the thinking level, not the operational level. In my head, I was thinking "how do I describe this feature to readers," not "first press Ctrl+1 to switch to the left editor, then Ctrl+\ to open the preview."
That's the effect I was aiming for. A tool that quietly does its job when you don't need to be aware of it.
MyST Notebookhas been officially published on the Marketplace — the v0.1.3.vsix. I absolutely need to polish it. If you write technical documentation, use the Jupyter Book or MyST ecosystem, or have been stung by any of these pain points, follow this, try this. Any issues are welcomed on Github~
If you also have a pile of Markdown in VS Code, and you too want to say goodbye to those preview panes — then perhaps this extension is for you.
Top comments (0)