Skip to content

Try our new Crash Courses!

Buy one of our new Crash Courses, now hosted on Teachable.

Why should I use Markdown?

Summary

Markdown is a language used to create README.md files that can be added to your projects.

Details

According to CommonMark, Markdown is “a plain text format for writing structured documents.” It’s somewhat similar to HTML in that it adds structure to a document and can be used to identify headings, lists, bold, and italic text, among other things. However, its syntax is very different.

Here’s a sample of a Markdown file:

# Grocery List

Below is a list of things I need to buy today.

* Milk
* Eggs
* Bread

Although there are some symbols you might not recognize, hopefully you can see that there is a title, a sentence, and a list. The extra symbols are identifying those sections of the document.

Here’s an example of what this code would look like when rendered:

Note: On CodePen, Markdown is rendered using a serif font, while on GitHub it’s rendered using a sans-serif font.

README files

In terms of development, Markdown has a couple of uses. Many projects include a file named README.md which uses Markdown (.md is the file extension for a Markdown file). The format of a README.md file varies, but it generally contains additional information about the project, like how to get started using a project, how to contribute to the project, and who created the project.

For personal projects, you can use the README.md file to store helpful notes.

On GitHub (a website for backing up coding projects online and collaborating with other developers), the README.md file will be displayed prominently on the front page of your repo. The various elements (like the headings, lists, bold and italic text) will be rendered properly (you can also see the raw syntax on GitHub as well). You can see an example of this on the Bootstrap repo on GitHub.

Static site generators

Markdown is also used with some tools for making websites, like static site generators. Some static site generators (like Gatsby) can take Markdown files and convert them into HTML files. This makes it easier to write new content for the site, especially if the site has a blog.

Different versions of Markdown can also be used inside certain applications, like Trello and Slack.

Exercises

You can download exercises to go along with these tutorials on our Markdown exercises GitHub repo. Just click the green Code button in the corner and click the Download ZIP option.

Each module has a folder. Inside each module folder is a folder for each lesson. The lesson folders usually contain files already where you can put your code, although occassionally you will be asked to create files on your own.

NOTE: You can ignore the instructions included in the folders. The instructions are now listed directly in the lessons.

References

CommonMark

Lesson tags: Free Lesson
Back to: Markdown Reference > Markdown Syntax