Better Markdown in Visual Studio Code

This entire post was written using Markdown in Visual Studio Code. That may seem a bit ridiculous. However, with a few tweaks VS Code can become an excellent tool for writing.

Writing in VS Code doesn’t have the features of Ulysses, the Syncing of Bear App or the polish of IA Writer. It doesn’t have a mobile app. However, it is free and the experience is quite good. If you’re considering a new Markdown editor, it is worth a try—especially if you’re an engineer.

The trigger for me was a new work computer. My old 2015 Macbook Pro couldn’t hold a charge. Previously, I had Typed, a now discontinued product from RealMac Software. It was fine until it began playing zen music on startup—an odd feature for a text editor. Despite my effort to disable it, I could not fix this issue. I needed a new Markdown editor.

Unfortunately, dealing with the Mac App store is a giant pain on work computers. That ruled out a lot of options. I tried many free tools, but none of them felt like a decent writing option. There were tons of bad fonts, contrast or typesetting.

Then I decided to see if I could wrangle VS Code into a decent writing experience. It’s pretty customizable, right? I was pleasantly surprised.

About Visual Studio Code

If you’re not an engineer, Visual Studio Code is a text editor. It’s what many engineers at my company, SalesLoft, use to create software. Don’t let that scare you though. It’s an excellent tool for writing.

First you’ll need to Download VS Code from Microsoft. It’s free for Mac and Windows. Once you do that, we’ll install extensions and tweak a few settings.

Extensions

Extensions in VS Code are similar to browser extensions. They are little pieces of software that enhance another app.

I’ve listed the extensions we need below. To begin installing them you can click the blocks icon in the bottom of the navigation bar or you can hit CMD + Shift + X. This should open an extension search bar. Simply search for the ones below and hit the green install button when you find it.

Alternatively, clicking install from the links should prompt you to open and install the extension in VS Code.

Markdown All in One is a requirement for anyone that wants to write in Markdown. The extension adds keyboard shortcuts, sane formatting for tables of contents and lists, Markdown tables and a few other enhancements.

Code Spell Checker catches common spelling mistakes. It’s useful since VS Code does not have spellcheck installed by default.

The implementation is a little strange—a light bulb appears above the paragraph with an issue. However, it didn’t take long to get used to, and even the best writers need spellcheck.

An interesting side effect of this type of spell check is that I try and guess the correct spelling of the word instead of right clicking and selecting the first option. Maybe this is a good interaction in the long run?

Word Count adds a small word counter when working in a Markdown file. Helpful, but not required.

Wanted: A Hemingway-like extension. Hemingway is a decent editor with one killer feature. It highlights complex sentences, passive voice and suggests phrases with simpler alternatives. I would love something like this for VS Code. Ideally, the feature can be toggled with a shortcut.

Settings

Once you’ve installed VS code and the related extensions, we’ll tweak the settings to improve the writing experience.

To get to the settings tab hit CMD + , or click the cog icon in the bottom left of VS Code.

Then we’ll want to open the JSON view by clicking the icon with the page and arrow in the top right of the application. This is the JSON view of all your settings. Unless you’ve made a few changes, this file should be blank.

Paste the following code into that file and hit CMD + S to save. We’ll discuss what this does below.

{
 // Global VS Code Settings appear here 
     "[markdown]": {
     "editor.fontFamily": "\"IA Writer Duo S\", monospace",
     "editor.fontLigatures": true,
     "editor.fontSize": 16,
     "editor.lineHeight": 26,          
     "editor.wordWrap": "wordWrapColumn",
     "editor.wordWrapColumn": 64,        
     "zenMode.centerLayout": true,
     "editor.lineNumbers": "off",
     "editor.quickSuggestions": false,
     },
 }

Markdown-specific settings

You might have noticed [markdown] in brackets. What this does is help us separate settings from Markdown files from other file types. If you’ll use VS Code for writing software, you’ll want to do this. Otherwise, it’s probably fine to have these settings at the global-level.

Typography

The first setting here changes the font to Duo, an excellent open source font from IA Writer. The font is based on IBM Plex Mono, which is also an excellent font. Here’s what IA says about it.

What is Duospace?

Duospace is a notion familiar from Asian fonts where there are single and double width characters. Our candidate is a bit different. It offers single and four 1.5 width characters.

Duospace gives 50% more space to the letters m, M, w and W. It takes two of those to get back in step with the monospace rhythm. The advantage over proportional fonts is that you keep all benefits of the monospace: the draft like look, the discernibility of words and letters, and the right pace for writing. Meanwhile, you eliminate the downside stemming from mechanical restrictions that do not apply to screen fonts.

You can use Menlo or whatever default fonts you’d like here, but I’d strongly encourage you to download Duo. Especially, since it’s free. If the monospace style isn’t for you, consider Quattro.

Here I’ve changed the font size to 16 and the line height to 26. This size and leading change makes the text much easier to read. If you’d prefer a larger font than 16, multiply the font size by 1.6. This is a foolproof way to get legible text. For example you could use font size 18 and line height 29 or font size 20 and line height 32. Play around with it and see what works best for you.

The last type setting here enables font ligatures. The main reason you’ll want this is so the italic version of a font to be used when you’re writing italicized text.

Text wrapping

The second set of settings control text wrapping. Most text editors are meant for code, not articles, and disabled wrapping help makes that easier to read.

However, if you’re trying to read a paragraph like this you want lines to be between 60 and 80 characters. Anything longer than that and it becomes uncomfortable to read. Personally, 72 characters is about right for me.

VS Code features

The final settings here alter a few VS Code features to make writing a better experience. Line numbers just add noise when writing, so it’s best to remove them. Quick suggestions are helpful for inserting variables you’ve previously used but will become a nuisance when writing your blog post.

Then there’s the Zen Mode setting, which forces a center column when in Zen Mode. You can enable Zen Mode at any time by pressing CMD + K and then Z.

Themes

This section was going to be about the best writing VS Code themes I found. After experimenting with a few options, I’ve decided the basic Dark+ theme works better than anything I found though.

Other tips

Sometimes it’s helpful to have a separate page of notes. You can click the split screen icon and use one markdown page for notes and the other for your article. Depending on your screen size you may need to adjust the word wrap or font size to prevent horizontal scrolling.

There are a few ways to center the text in VS Code. The first thing I tried was by going to View > Appearance > Centered Layout. However, it seems a little noisy. I prefer dragging the menu bar out a little further is an easy way to center the text.

There are some code editor features that are pretty useful when writing. For example, I always have the outline tab open to the left. When writing in Markdown, it populates headers and subheaders. It’s useful when working on long-form posts.

There’s a little icon with a split-screen and a magnifying glass. This opens a preview of the file the Markdown stripped away. It also makes it easy to copy the text to WordPress. That’s how this post came to be!

If you only plan to use VS Code for writing, consider setting Markdown as your default file type. You can do that by adding the following to your global settings.

"files.defaultLanguage": "markdown",

At this point, you’re all done configuring Visual Studio Code for writing Markdown. Your next blog post awaits!

References

Chris Chinchilla, Customizing Visual Studio Code for Writing, Hacker Noon, Published 6/14/2019

Writing Mode in VS Code, Diéssica Gurskas, Published 2/28/2018

J/A, VS Code: markdown and word wrap, Smokeless and Unleaded, Published 4/28/2018

Oliver Reichenstein, Duospaced! In Search of the Perfect Writing Font, IA.net, Published 11/23/2017

Typed.com is Closing Down, RealMac Software, Published 8/3/2017