Markdown – How to Style Text on GitHub and the Web


Markdown is a popular and simple way to style text using an easy to read syntax of symbols. It allows you to format your documentation and since the style itself is saved in-line, it's easy to track changes with git or your version control of choice. This article will cover the basic of Markdown and link to a cheatsheet for you to start using today!


What is Markdown?

Markdown is a way to style text on the web to add headers, format words as bold or italic, add images, creating list, and more. It's extremely simple to learn as it just uses some simple symbols such as #, -, and * to denote the various desired styles. These files are saved in Markdown format (.md extension).

Why use Markdown?

Markdown allows your plain text documentation to be styled with what I like to call "Style as Code" similar to CSS for traditional webpages. We can collaborate on documentation, but not just the text within, the style and appearance of that text as well. Finally, because markdown is just plain text, git handles it perfectly so we can show a commit history of the changes to the styles, images, etc that are in our documentation.

Finally, this question of why can be answered with asking you if you'd format a word document. The answer is yes, and we do this kind of formatting to make the reading experience easier. On this article itself, we have headers that clearly define sections, URLs to other resources, embedded images, and more. All of this can be done with Markdown.

Guide to Markdown Syntax

Googling for a Markdown Syntax guide will provide many results, but I always turn to this printable cheat sheet from GitHub when I have a forgetful moment for things I don't do as often such as markdown tables.

The syntax itself is very simple however and easy to memorize for the simple styles you'll use regularly.

GitHub Flavored Markdown (GFM)

GitHub uses it's own flavor of Markdown syntax that extends the basic functionality shown above. These let you do things like syntax highlighting in code blocks, tables, task lists, emojis, and more. Many other sites also support these items, but since I always talk about GitHub, I wanted to include their version too. You can find this on page two of the above referenced cheat sheet.

Tools to help you write Markdown (.md) files

There are many, many, many tools that leverage markdown to help you do things like host a website on GitHub Pages, create a Jekyll blog, style your project board, and even format your Reddit post.

Check out this list of tools from Markdown Guide for more information. For me personally, I write my Markdown in GitHub's UI for minor changes, but love using Atom's markdown preview package when I'm doing things like inserting gifs, images, .mp4s, or tables as it provides a live preview of your formatted and rendered document.

You may also like

What is a “Lighthouse” Team?

What is a “Lighthouse” Team?

What is DevOps? What is DevSecOps?

What is DevOps? What is DevSecOps?
{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}

Subscribe to our newsletter now!