How to Easily Format Markdown Files in VS Code

Every respectable software project needs a README. This file provides crucial information about what the project is, how to work with it, and other relevant information for developers. README files are written in markdown, a special markup syntax. The syntax for markdown is simple enough, but it can be a pain to manually type out, and it’s easy to make simple mistakes and typos.

Wouldn’t you like to just use the Cmd+B keyboard shortcut to bold some text instead of typing ** around your text? Or what about creating a nicely formatted table in your README, especially when editing an existing table? Wouldn’t it be nice if the table formatting and column width adjustments were taken care of for us? Markdown is wonderful, but it’s not exactly as easy as working with a Google doc when applying formatting.

The SFDocs Markdown Assistant VS Code extension is here to help!

---

Common Use Cases

In this article, we’ll look at some common use cases when writing a markdown file. We’ll first look at simple text formatting like bold, italic, or strikethrough. Next, we’ll look at writing numbered lists. Finally, we’ll look at creating and modifying tables.

Let’s get started!

---

Bold, Italic, and Strikethrough Text

Let’s start with the simple stuff. In markdown syntax, you can make your text bold by wrapping your text in **, italic by wrapping your text in _, and strikethrough by wrapping your text in ~~. It’s not a huge burden to type out these characters, but it’d be really nice if we could just use keyboard shortcuts to format the text in the same way that we can when working with a Google doc.

Here’s the markdown we’ll use to apply these styles:

Markdown for bold, italic, and strikethrough text

And here’s what the output looks like when viewing the markdown file:

Output for bold, italic, and strikethrough text

Now, let’s show how easy it is to apply these various styles when using the VS Code extension! We can make our text bold using Cmd+B, italic using Cmd+I, and strikethrough using Option/Alt+S.

Demo for writing bold, italic, and strikethrough text

---

Numbered Lists

Next, let’s take a look at lists. When creating a numbered list in a Google doc, hitting the Enter key after typing your first list item creates the second list item with the 2. prefix already in place. In a markdown file, however, you have to manually type the number prefix for each item. It’d be nice if we could have that done for us automatically!

Here’s the markdown we’ll use to create a numbered list:

Markdown for a numbered list

And here’s what the output looks like when viewing the markdown file:

Output for a numbered list

Now, let’s show how easy it is to create a numbered list when using the VS Code extension! We start by typing 1. Bread to create the first item in our list. Then when we hit the Enter key, the next number prefix is added for us automatically!

Demo for creating a numbered list

---

Tables

Finally, let’s look at creating and modifying tables in markdown. Tables are easy enough to create, but a pain to modify, especially as the column widths change.

Here’s the markdown we’ll use to create a table:

Markdown for a table

And here’s what the output looks like when viewing the markdown file:

Output for a table

Now, let’s see a demo of how long it takes to create the table from scratch without using the VS Code extension. Note how much time we spend modifying the column widths, and we’re only doing this for a table with three rows! Imagine doing this with a much larger dataset and how much of a headache this would be.

Demo for manually creating a table

Now, let’s show how easy it is to create and modify a table when using the VS Code extension. For starters, we can insert an empty table by right-clicking in our file to open the context menu and then selecting “Table >> Table: Add.” We can then specify the number of columns and rows and hit Enter to create the dummy layout.

Then, as we enter text into the table, we can navigate from cell to cell using Tab and Shift+Tab. Whenever those keys are pressed to navigate to a different table cell, the column widths automatically adjust. This is probably my favorite feature!

Demo for creating a table using the VS Code extension to help

You can find even more cool features in the right-click context menu or by reading the extension’s docs.

---

Conclusion

This markdown tool is incredibly simple, but it’s often the simple things that make the developer experience better. The SFDocs Markdown Assistant looks like a VS Code extension I’ll be keeping around!

Comments

[UchiTesting]

Hello,
I love markdown. I love clean code and layouts. And I would write a table in markdown like you showcase in the beginning. Because it looks clean.

But I had time to realise I was just making my life difficult.
Eventually I read the markdown in a viewer. Also I can take the table not being aligned when I edit it. I know it will look good.

The minimum markup for a table is

||
|-|
||

Here is an example of what I have in a document

| Optimistic | Pessimistic |
|---|---|
| Considers the update will be successful. | Wants to reflect the actual status of exchange. |
| Updates the view 1st then call the API. | Calls the API, then updates the view. |
| Do not need to keep the previous state. | Needs to keep the previous state to restore it should there be a failiure. |
| Do not need extra code to manage exceptions.| Needs to manage exceptions with extra code. |
| Simpler code. | Gives the user the illusion of a fast application.|

And this is how it displays:

Regards.

[Tyler Hawkins]

Great callout! Yes, absolutely, the table still looks ok in the actual markdown output even if the markdown source code isn't perfectly aligned.

This is probably just the perfectionist in me that likes to see the source code nicely aligned. Or, with a much larger table with many columns, I imagine there is some real benefit to having the table aligned nicely for ease of editing.

The good news is that now with all the handy VS Code extensions out there (or whatever IDE you might prefer), it's also pretty simple to get the source code itself formatted nicely without a lot of effort on your end!