We all need documentation to understand how a new API works, and nothing turns me away faster from learning something new than poorly presented documentation. Grammar or spelling aside (you should always do a double check!), here’s how to use a very basic and powerful, easy-to-use formatting language called Markdown.
Markdown is a markup language that’s meant to be easy to read and format. Its main source of inspiration is a plain old email. There aren’t a lot of features, but for a simple README file, it’s plenty. With these easy options you can create an inline html file for viewing on the web. Let’s go through the essential syntax and best practices…
Note: I will be going through the Github Flavored Markdown variant. Markdown itself has been around since 2004, but in 2017 GitHub created its own fork of the language. To my knowledge, it is the most widely used version only because of the sheer number of developers that use GitHub.
There are three different sized headers which correspond to the html tags:
# Title ## Subtitle### Header
Style tip: It is good practice to always leave space between the title and whatever is to follow, and to never end a title with a
:. I strongly suggest picking up a Markdown linter. It will help make your Markdown easier to read and edit going forward. (I will link to these at the end of the article.)
Bold and Italic
To add emphasis on text, we can utilize bold and italic.
Style tip: You should avoid using emphasized text as headers. These emphasis tags are meant to be used in a the text body not in the headers.
To add unordered and ordered lists, use the following tags:
3. three- one
Whether you are using ordered or unordered lists, the text will automatically be indented to the page. These are the same as the
<li> html tags.
I strongly recommend checking the following extension for vscode. Although Markdown is not hard by any means, it’s always nice to have intellisense to explain the proper format. This one extension is a pack that will install a collection to make editing with Markdown easier.