Enhance your Markdown experience using vscode
Follow me on Twitter for more AI / Cloud / Tech related stuff!
Everyone love markdown. From GitHub’s readme to static website the language is everywhere. Facebook also adopted it for its latest documentation tool Docusaurus. There are plenty of options to write in markdown ! It can be edited in your IDE, in text editor (like vscode, coincidende ?), terminal, dedicated desktop apps or even web apps. No other writing “language” is such ubiquitous. I’ve used markdown for years because of its features and growing ecosystem. It’s now my go-to language when editing readme, documentation, blog post (i’m writing this in markdown), and other business related documents.
Why do I prefer markdown to, let’s say, word docx format? To begin, it’s far more easier to track change in source control version like git, and thus collaborate with others. Very often, i have to export documents for colleagues, customers, etc. Using tool like pandoc or markdown all in one extension make it possible to export in PDF format. Of course, every steps are automatable, and it’s not rare that I write makefile (bash script) or use Continuous integration (think jenkins or gitlab CI) for automatic export of my docs and delivery to some website/cloud/shared folder.
Disclaimer : If you use markdown to mainly write blog post, and are not afraid of commercial products, go and buy an existing application. It will be great for this type of task.
So, what is this article about ? I’ve tested several combination of editor, plugin, theme, etc. to try to create the best markdown editor for me. Disclaimer : If you use markdown to mainly write blog post, and are not afraid of commercial products, go and buy an existing application. It will be great for this type of task. There are plenty of options, on mac, linux, windows, web. But I need flexibility. I need to be able to mess with the CSS of my PDF (more specifically, with the CSS of the intermediate HTML document, but that’s technical details). I want to have git support right in my editor. I want to edit makefile or ci pipeline file. Or even the possibility to store pandoc configuration right along my markdown. Last but not least, I want to be able to do real-time collaboration on my documents. For that, nothing beat vscode. But there is A LOT of theme/plugins/configuration available, and this article is here to guide you through them to what I think is one of the best markdown writing experience on vscode.
Plugins
In my setup I use these plugins:
Markdown all in one is providing me multiples tools to ease the writing of markdown files. I encourage you to check all the features it has to offer, it’s a great extension.
Markdown lint do a simple job, but do it well. As its name suggests, it’s a linter. Since you can consider markdown as a textual programing language, it can be useful to check against bad practice when writing. Also this will become mandatory when collaborating to ensure that your text doesn’t become a big mess.
And lastly, vscode-pandoc permit… to use pandoc in vscode. The tool in itself is just a shortcut to pandoc, so you will have to install it separately. But it also offer configuration integration. Being able to store pandoc configuration in vscode configuration file is super handy as it will result in cleaner, and thus easier to understand file structure. One frequent usage is to pass a css file to pandoc to customize pdf output like in the following example.
Note that you also need to install wkhtmltopdf to use css in pdf generation. If you’re on mac, brew cask install wkhtmltopdf will do the trick.
//-------- Pandoc Option Configuration --------// pandoc .pdf output option template that you would like to use
"pandoc.pdfOptString": "-t html --css style.css",
Here is a simple style.css, you can really do what you want here.
body {
font-family: fira sans
}Eventually, this configuration give you more flexility in the output than 90% of available editors. And since everything is based on cli (pandoc) and configuration files, a CI/CD pipeline would have everything it needs to reproduce your output. When you start combining CI and markdown, a whole new world of possibility become available.
Theme
In traditional markdown apps, you have 5, maybe 10 themes to choose from. In vscode you have hundreds ! It’s totally up to your personal preference, but I would recommend using Atom one light or One Dark Pro for markdown editing. I personally prefer using light theme for writing, and dark theme for coding. Having to switch from theme to theme quickly become boring. We will see in the next part how to leverage vscode settings mechanism to have workspace specific configuration.
I think that a beautiful font is mandatory when typing. Mozilla is offering the open source Fira fonts familly which is a great free options to write documents. I personnaly use Fira sans but Fira sans condensed is also a viable option depending on your taste.
Configuration
So, how can I override global parameters to not have to reset my theme/fonts every time I write markdown ? You can leverage the .vscode/settings.json to do so. If vscode detect this file in your workspace, the specific parameters will override the global ones.
Here are my personnal parameters:
{
"editor.fontSize": 16,
"editor.fontFamily": "fira sans",
"workbench.colorTheme": "Atom One Light",
"editor.scrollbar.vertical": "hidden",
"pandoc.pdfOptString": "-t html --css style.css"
}Let’s review them.
“editor.fontSize”: 16. I like to have a bigger fonts when writing (especially on a retina display)
“editor.fontFamily”: “fira sans”. This one set a local font family
“workbench.colorTheme”: “Atom One Light”. Set the local theme
“editor.scrollbar.vertical”: “hidden”. I use a non official parameter to hide the scroll bar (need a vscode restart). This is mandatory for the focus mode experience we’ll see later.
“pandoc.pdfOptString”: “-t html –css style.css”. Set my pandoc options as seen previously
Focus mode
More and more editor offer a focus mode / zen mode. Vscode always had the Zen mode (Or maybe since a long time…). But the text still wasn’t centered on the screen which can lead to ugly interface on an ultra wide monitor. Even on my laptop, it was not so beautiful… But recently, the editor introduced centered layout to solve this issue !
So to enjoy a beautiful experience, now you can cmd+shift+A > Toggle zen mode then cmd+shift+A > Toggle centered layout.
You should experience something like:
Conclusion
So now, we should have covered how to use vscode, plugins, theme, pandoc, and configuration to have a replicable, flexible writing environment in vscode.
Don’t hesitate to share your setup !
