Visual Studio Code for prose
for pros
June 12, 2020 — March 3, 2023
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:
- Brano Sandala’ssurfinzap/typopo-vscode: Fix frequent microtypography errors in multiple languages. Write neat texts without bothering about typography rules. Typopo works for English, German, Slovak, Czech and Rusyn language. - see Typopo project site
- rusnasonov/vscode-typograf: Helps to automatically place the non-breaking spaces, correct small typos, replace the quotation marks to a correct format and much more.
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):