Visual Studio Code for prose

for pros

June 12, 2020 — March 3, 2023

computers are awful
faster pussycat
plain text
UI
workflow
Figure 1

VS Code is a code editor but also a text editor. For me usually “text” means text formatted as markdown, esp Rmarkdown or quarto, but it can sometimes mean LaTeX. I would like various things to work smoothly in VS Code for prose, even though the editor is really set up more for code.

1 Word counting

A fancy option is word counter.

2 Markdown hacks

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

For RMarkdown, Tianyi Shi’s excellent RMarkdown all-in-one extension is useful.

For editing any plain-text blog, e.g. blogdown, anin-app browser preview can be useful.

vscode-paste-image pastes images from the clipboard.

3 Integrating text generation

text generation is useful. I find github copilot to be pretty good There is also gencay.vscode-chatgpt which integrates ChatGPT.

4 Spell checking

There are three major options.

4.1 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 personally but whatevs.

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

4.2 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 I 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
        ],
    },

I had to make sure that my spelling language is set to a supported dictionary, or I would miss things.

On Ubuntu I need hunspell dictionaries installed. NB it was not sufficient to install hunspell; I needed 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. I can create my own language if you want, so that’s nice I suppose. More usefully for most of us, can create my own user dictionary, or add to it using hunspell commands but it’s not clear to me if VS Code will pick these up.

You know what? After all that I think I have persuaded myself that this is not quite the right way to do things. There is another alternative

4.3 LTEX

LTEX:

LTEX – Grammar/Spell Checker Using LanguageTool with Support for LATEX, Markdown, and Others

LTEX provides offline grammar checking of various markup languages using LanguageTool (LT). LTEX can be used standalone as a command-line tool, as a language server using the Language Server Protocol (LSP), or directly in various editors using extensions.

LTEX currently supports BibTEX, ConTEXt, LATEX, Markdown, Org, reStructuredText, R Sweave, and XHTML documents.

The difference to regular spell checkers is that LTEX not only detects spelling errors, but also many grammar and stylistic errors…

A classic use case of LTEX is checking scientific LATEX papers, but why not check your next blog post, book chapter, or long e-mail before you send it to someone else?

The java ltex server is memory-heavy; I recommend not enabling this extension globally but only when editing an actual LaTeX document.

5 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.

5.1 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.

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.

5.2 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 (😐)

5.3 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

6 LaTeX

See VS Code for LaTeX.

7 Automatic typographical fixes

I am auditioning these:

So far the first one, typopo is working OK, although it could me more configurable, e.g there is no way to disable the non-breaking spaces feature around short words.

8 Full-text indexing

Fuzzy, information-retrieval-style search would be nice. I do not know if integrated solutions Vladimír Zdražil demonstrates. an integrated workflow via the shell, however.

9 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"
        }
    }
]