Editing Markdown in Visual Studio 2015

It seems that every day I find myself editing markdown files more and more. I like the simplicity of markdown when it comes to creating documentation. While I realize that markdown isn’t nearly as flexible as full-on HTML I like that it forces me to keep my documents simple and clean.

I’ve tried a LOT of markdown editors. I’ve tried on-line editors as well as editors I’ve installed on Windows. For me, personally, I prefer to have the editor installed on my machine in case I want to edit documents offline.

Lots of Choices!

For the past couple of years I’ve been using a tool called MarkdownPad 2. While this is a capable editor it doesn’t seem to be updated any more. If you want it to work on Windows 10 you have to make sure the appropriate display software is installed. One feature that MarkdownPad does not have that I’d really love to have is integration with Git repos. I’ve started moving down the path of storing markdown files in Visual Studio Team Services (VSTS) and publishing the markdown, as HTML, to various WordPress sites for consumption (via the Markdown to WordPress VSTS extension). So, with the desire to have integrated Git integration within a markdown editor, I’ve once again started looking…

Visual Studio Code

Since I knew that VS Code integrates with Git and also renders markdown files that was my first stop. While VS Code does a great job at rendering markdown, you can even have the editor and the preview side-by-side (see image below), it does not keep the editor in sync with the preview when scrolling.

That said, I did request this feature on the VS Code GitHub site, here, in case you have an interest in contributing to the code base and making me (and many others) happy :-)

Visual Studio 2015 to the Rescue!

Although VS 2015 does not feel as “light” as VS Code it is (obviously) a very capable editor. So it should be no surprise that it can also edit markdown files.

If you open a markdown file in VS 2015 “out of the box” the results will look something like this:

In other words, it’s simply a text editor with some URL highlighting capabilities.

However, if you sprinkle in a little Visual Studio extension magic provided by Mads Kristensen then you’ve got something truly useful!

To install the extension:

1. In Visual Studio 2015, click on Tools->Extensions and Updates.
2. Click the Online node and search for Markdown Editor.

   

3. Install the extension.

Now, with the extension installed, when you open a markdown file it will look something like this:

Not only is the markdown text and preview rendered side-by-side, the preview will attempt to stay in sync with the editor as you scroll the editor up and down! While it’s not perfect (i.e. the two don’t always sync exactly in line with each other) it’s still a pretty good experience. And, of course, Visual Studio has Git integration so this is exactly what I have been looking for!

But, wait, there’s more!

As if that wasn’t enough already, Mads has also address the other major pain in my life when it comes to editing markdown files — pasting images!

If you’re thinking, “I’d love to copy an image to the clipboard and simply “paste” it into my markdown text and have the editor automatically save the image to a file and then insert the appropriate markdown for rendering the image”, then that’s exactly what you get!

Yes, you read that correctly… you can simply paste an image into the markdown text and the extension will ask you where you’d like to save the picture and it does the rest! If you’re storing your markdown files in Git (or some other VCS) then this is the icing on the cake :-)

Check the Options…

If you give it a try make sure you check out the markdown options. Press Ctrl+Q and type in “markdown” and hit enter. You will see various options that you can modify to tweak the markdown editing experience.

If you’d like to read more about this extension – or simply take a look at its source code – check it out on GitHub, here.

I will be giving this approach a try for the next few weeks to see how it compares to MarkdownPad. However, with Git integration, synchronization capabilities, and the ability to paste images, my hunch is that it will be hard to be Visual Studio 2015!

If you have experience with other markdown editors that a) have Git integration, b) syncs the editor with the preview panes, and c) manages images, then please comment about them below :-)