Sometime after he created Linux, Linus Torvalds created Git. Git is the most widely used distributed version control system in the world. If you use Git, you should be using markdown to document your work. Per Wikipedia, "Markdown is a lightweight markup language with plain text formatting syntax". It supports formatting, images, even inline HTML for formatting when markdown does not have a native option.
Here's a quick table of contents for this article:
Even if you have NEVER written markdown, we have something special help you move from walk to run very quickly. If you use markdown today, we are going to share some resources that will raise your game.
NOTE: We know many of you use Git already, but are interested to hear how many of you do not yet. We will definitely touch on Git soon for those in the "don't know Git" category.
SPONSOR: Need to stop and start your development VMs on a schedule? The Azure Resource Scheduler let's you schedule up to 10 Azure VMs for FREE! Learn more HERE
If you use VS Code, you know extensions are a big part of what makes VS Code great. I like to pick extensions that are
- widely used (thousands of downloads)
- highly rated (4+ stars)
- frequently updated.
Below are the three free extensions I use for optimizing my markdown authoring efforts in VS Code:
-
Markdown All in One. This includes keyboard shortcuts for formatting your content, easy list creation, and a great markdown preview feature so you can see how your markdown will render. It also includes a super-handy export to PDF, HTML, and PNG options, so it's perfect for sharing documentation with a colleague outside your dev team. It even makes creating and formatting a table of contents in your documents much less work if you like.
-
Markdown Lint. This extension offers markdown linting and style checking, steering you to be consistent with best practices in your markdown. While the previous extension makes writing markdown faster and easier, Markdown Lint ensures your markdown is consistent, and syntactically correct.
-
Spell Right. This is a multilingual, offline and lightweight spellchecker. It checks your spelling as you type, and when you run your cursor over a word, it provides alternatives. Make sure to read the directions for this one, as you have to download the dictionary file for your language from their Git repository.
Figure 1. Verifying VS Code extensions are installed (bottom right of VS Code)
The steps for installing these extensions varies by extension, so you do want to read the instructions. If you have never installed an extension in VS Code, you will want to read this Extension Marketplace article.
To ease the process, we created this Markdown Cheat Sheet. It includes both the syntax for a wide variety of markdown commands, as well as an example of how that syntax renders. You can use the hyperlinked table of contents and 'back to top' links to navigate this document quickly and easily in a browser. If you prefer, here is fully functional PDF version.
We hope this removes any excuses that have prevented you from properly documenting your work in Git. Even if you' have never written markdown, this will get you up and running quickly. So, create a link to this markdown cheat sheet, or simply download the PDF version. Then, take 10 minutes to get these extensions installed, and start documenting!