Visual Studio Code for prose

for pros


VS Code is a code editor but also for text. For me usually this means markdown, but it can also mean LaTeX.

Word counting

The fancy one is word counter.

Markdown hacks

Markdown all-in-one dos nice things like wrap things in links and autogen tables-of-contents.

If you are using RMarkdown, Tianyi Shi‘s excellent RMarkdown all-in-one extension is useful.

vscode-paste-image pastes images from the clipboard.

Spell checking

There are two major options.

cSpell

The most popular seems to be cspell a.k.a. codespell, which is VERY EXCITED about GETTING CODE SPELLING RIGHT including SPELLCHECKING VARIABLE NAMES, which is a low priority for me but whatevs.

Pro
It works fine with no messing around.
Con
It keeps your user dictionary in your settings which results in massive settings files.

Spellright

Aesthetically I prefer SpellRight as far as system spellcheck integration. Developer Bartosz Antosik is incredibly responsive.

Pro
Works with system dictionaries
Con:
System dictionary support is more complicated than you would hope.
It is too aggressive with spellchecking markup in markdown.
Clashes with the LaTeX extension.

Here is a workaround I whipped up, to put in the settings file:

    "spellright.ignoreRegExpsByClass": {
        "markdown": [
            "/@[A-Za-z0-9_]+/g", //citations
            // "/```(.+?)```/gm", // code blocks - does not work.
            "/`[^`]+`/g", // code inline
        ],
    },

Pro-tip: make sure that your spelling language is set to a supported dictionary, or you will miss things.

On Ubuntu you need hunspell dictionaries installed. NB it is not sufficient to install hunspell; you need to download or link the files into the right place for the extension to find them, in the correct character encoding.

To use it a pair of Dictionary (*.dic) and Affixes (*.aff) files with UTF-8 encoding have to be downloaded … and placed in Dictionaries subfolder of VSCode’s user global configuration directory, located at $HOME/.config/Code/Dictionaries/.

Hunspell dictionaries are not obvious, entailing e.g. character set weirdness. You can create your own language if you want, so that’s nice I suppose. More usefully for most of us, can create your own user dictionary, or add to it using hunspell commands but it’s not clear to me if VS Code will pick these up.

Markdown mathematics

VS code comes with a built-in markdown preview, but it is missing mathematics support. You want mathematics, right? Yeah you do.

You can make Markdown more legible in dark themes by using Markdown Theme Kit, bitbucket styles or github styles. Markdown all-in-one has basic mathematics support.

Browser preview

If I’m doing e.g academic blogging, my site previewer already has robust preview in the browser. It is simple and robust and I currently recommend it. It is not fast, but then neither are the alternatives and at least this one .

Pros:

Supports everything the blog itself supports

Breaks in the same way that the blog itself will break when something goes wrong instead of exotic local ways
Cons:

Need to manually launch browser preview

Slow, although hard to say if it is actually slower than the alternatives.

Native “Markdown + Math”

You can augment native markdown preview with maths support via Markdown + Math a.k.a. mdmath.

Pros:

Renders math faster using KaTeX

well integrated with everything else
Cons:

mdmath KaTeX macro support is quirky, as the underlying KaTeX macro support is in turn quirky. Further, to detect macro updates you need to close and open the window again.

The parser is bad at identifying delimiters — in particular,

  • There must be a blank line before display math and some kind of whitespace after it. (😱) If I generate LaTeX from the markdown, there will be semantically-incorrect paragraphs before each equation.
  • No newlines in inline math (😬)
  • No spaces between delimiter and math (😐)

Markdown preview enhanced

Replace native markdown preview with the revamped Markdown Preview Enhanced.

Pros:

Just works

Supports MathJax and hence LaTeX-native macros
Cons (at least when using MathJax):

Slow, presumably due to MathJax being slow

leaks RAM
eventually crashes

LaTeX

See VS Code for LaTeX.

Maths snippets

Here is a example set that works well for markdown maths:

{
  "Inline_Math": {
    "prefix": "$",
    "scope": "markdown,latex",
    "body": [
      "\\($1\\)",
    ],
    "description": "inline math"
  },
  "Display_Math": {
    "prefix": "$$",
    "scope": "markdown,latex",
    "body": [
      "\\[",
      "$1",
      "\\]",
    ],
    "description": "display math"
  },
  "Display_Math_Markdown": {
    "prefix": "align",
    "scope": "markdown",
    "body": [
      "\\[\\begin{aligned}",
      "$1&=$2\\\\",
      "\\end{aligned}\\]",
    ],
    "description": "display math"
  }
}

Or for a short-ish snippet you can assign direct keyboard shortcuts in the keybindings.json file (Preferences: Open Keyboard Shortcuts File):

[
    {
        "key": "ctrl+shift+4",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "\\($1\\)$0"
        }
    },
    {
        "key": "cmd+shift+4",
        "command": "editor.action.insertSnippet",
        "when": "editorTextFocus",
        "args": {
            "snippet": "\\($1\\)$0"
        }
    }
]