DEV Community: RequieMa

Farewell, All VS Code Preview Panes

RequieMa — Sat, 18 Jul 2026 13:51:56 +0000

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's md.renderInline(), and there's no way around it for now. While editing, they appear as plain text; jupyter-book build will 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 Notebook has 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.

How To Build A Personal Blog With MkDocs

RequieMa — Sun, 12 Jul 2026 03:26:48 +0000

How This Blog Was Built

The first post is about the blog itself — a write-up of every decision and step that went into putting this site together.

If you are setting up a similar lightweight developer blog with MkDocs Material, this should save you a couple of hours.

Why MkDocs Material?

I wanted three things:

Write posts in Markdown — no CMS, no database, no WordPress.
Deploy on every git push — GitHub Actions builds the site and deploys to GitHub Pages.
Bilingual out of the box — English and Chinese, with search that handles both.

The blog plugin is first-class, not an afterthought.

Step-by-step Setup

1. Scaffold

uv manages dependencies with a lockfile (uv.lock) so builds are reproducible.

uv init
uv add mkdocs-material pillow cairosvg \
  mkdocs-git-revision-date-localized-plugin \
  mkdocs-rss-plugin

After that, mkdocs.yml and docs/index.md are the only files you touch. Replace index.md with your landing page.

Local dev server:

uv run mkdocs serve    # → http://127.0.0.1:8000

2. Core Configuration

mkdocs.yml is the single source of truth. Here is what goes in:

# Blog plugin — posts, archive, categories, pagination
plugins:
  - blog:
      blog_dir: blog
      post_dir: "{blog}/posts"
      archive: true
      categories: true
      pagination: true
      pagination_per_page: 10
      authors_file: "{blog}/.authors.yml"

  # Tags — auto-generates tag index pages
  - tags

  # Search with Chinese tokenization
  - search:
      lang: [en, zh]

  # RSS
  - rss:
      match_path: blog/posts/.*

3. Bilingual Strategy

No separate site builds, no mkdocs-static-i18n plugin. Just a directory convention:

docs/blog/posts/
├── en/    ← English posts go here, tagged `english`
└── zh/    ← 中文文章放这里，tag `chinese`

It may be time-consuming for writing articles in two different languages. However, I prefer a full control of the content I wrote.

Search indexes both languages — the lang: [en, zh] line above tells the built-in segmenter to handle CJK characters. Readers filter by language via the tag system.

4. GitHub Actions CI

A single workflow file (.github/workflows/ci.yml) does three things on every push to Master:

Checkout the repo (full depth, needed for git-revision-date-localized)
pip install dependencies + mkdocs build
actions/deploy-pages to publish

Set Settings → Pages → Source → GitHub Actions in the repo and you are done.

5. Analytics & Comments

Google Analytics 4 — one block in mkdocs.yml:

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX

giscus — free, no-ads comment system powered by GitHub Discussions. Enable Discussions in the repo settings, install the giscus app, and drop the repo/category IDs into mkdocs.yml.

6. Theme Polish — Atom One Dark Pro

This site doesn't use the stock Material palette.

Colors are inspired by Atom One Dark Pro -- I always like this palette, and was really sad when Atom stopped updating 😿. All overrides live in a single CSS file (docs/stylesheets/extra.css) loaded via extra_css.

Dark mode (default):

Variable	Hex	Usage
Background	`#282c34`	Page body
Surface	`#21252b`	Code blocks, sidebar
Text	`#abb2bf`	Body copy
Primary	`#61afef`	Links, header
Accent	`#56b6c2`	Hover states

Light mode:

Variable	Hex	Usage
Background	`#fafafa`	Page body
Surface	`#ffffff`	Cards, sidebar
Text	`#383a42`	Body copy
Primary	`#4078f2`	Links, header
Accent	`#0184bc`	Hover states

Key CSS snippet:

[data-md-color-scheme="slate"] {
  --md-default-bg-color: #282c34;
  --md-primary-fg-color: #61afef;
  --md-accent-fg-color:  #56b6c2;
}

[data-md-color-scheme="default"] {
  --md-default-bg-color: #fafafa;
  --md-primary-fg-color: #4078f2;
  --md-accent-fg-color:  #0184bc;
}

The home page gets a hero layout — large title, single-line subtitle, and Material's .md-button classes for CTA links. Blog post cards have rounded corners, subtle backgrounds, and a hover lift effect. A fadeIn animation smooths page transitions.

Dark mode is set as the default — the slate palette entry is listed first in mkdocs.yml.

Writing a Post

Every post is a Markdown file with frontmatter:

---
date:
  created: 2026-07-10
categories:
  - en             # language category: en or zh
  - topic-name
tags:
  - english     # or chinese
  - topic-tag
authors:
  - requiema
---

# Title

Content goes here.

Drop it in docs/blog/posts/en/ or docs/blog/posts/zh/, commit, push — the CI pipeline handles
the rest.

Summary

Dimension	Choice
SSG	MkDocs Material 9.7
Hosting	GitHub Pages (Actions CI)
Language	`en` / `zh` via directory convention + tags
Search	Built-in, `lang: [en, zh]`
Analytics	Google Analytics 4
Comments	giscus (GitHub Discussions)
RSS	`mkdocs-rss-plugin`
Writing	Markdown + YAML frontmatter

The full config is in the repo source.

Go write something~