GitHub is the largest code host in the world.
With over 13 million repositories, it’s a favored place for powerful collaboration. GitHub allows users to harness its extensive field-tested tools for both public and private projects.
It’s a simple and efficient way to use the power of the community (and GitHub tools) to test, create, and build.
As part of its inventory, GitHub uses a version of Markdown for simplified text formatting. It’s called GitHub Flavored Markdown (GFM).
In this article, I’m going to explain GitHub Flavored Markdown language—and how it differs from traditional Markdown language.
If you’re already familiar with Markdown, then grasping the use of GFM shouldn’t be difficult. But if you’re unfamiliar, you should probably brush up on some of the Markdown basics before tackling GFM.
Markdown provides the flexibility and precision that comes from writing your own HTML, but has the user-friendly nature that doesn’t require the use of over-complicated code.
At its core, Markdown allows you to format without taking your fingers off the keys. GFM extends this functionality by offering additional capabilities.
GFM is used extensively across the GitHub website—for issues, comments, and even pull requests. It’s conceptually the same as standard Markdown, but differs somewhat in its fundamentals.
In standard Markdown, you have to “set link text” to link to a URL. GFM allows you to easily link to the URL simply by typing out the URL name. For example: www.torquemag.io, would become www.torquemag.io
Unlike standard Markdown, GFM allows strikethrough text by adding 2 tilde characters [~] to the beginning and end of a piece of text. That means “I ~~still~~ used to smoke cigars” becomes: I
still used to smoke cigars.
Standard Markdown converts underscores into italicized text. For example: The _sky_ is blue, would become: The sky is blue.
GFM simply ignores this rule.
Fenced Code Blocks
Both GFM and standard Markdown support fenced code blocks, but differ in the implementation of it. While standard Markdown changes text that has four spaces before it into a code block, GFM renders the same result by wrapping your code in “`, like this:
``` this is the code block ```
GFM allows a syntax highlighting option to your code block. The syntax highlighting then uses Linguist to perform language detection on the respective code block.
In GFM you can create tables simply by compiling a list of words and then dividing them. Through the utilization of hyphens [-] and pipes [|] you can create a table, by dividing the first row with the hyphens and separating each column with a pipe.
In January 2013, GFM enhanced its structural capabilities when they announced their support of task lists.
To turn ‘regular’ lists on GitHub into structured task lists, just preface your list items with [ ] or [x]. The task list will then render checkboxes where you can check and uncheck each one. Alternatively, you can edit the text in Markdown, and the task list will automatically update.
Last month, GitHub announced:
. . . we are adding read-only task lists to all Markdown documents in repositories and wikis.
This feature extends the capabilities of GFM, providing options to help maintain organization and structure.
To implement, simply preface your list items with [ ] or [x]:
And it should render like this:
To make changes to the list, you should implement them in GFM.
Last week, the use for task lists was further extended when GitHub announced nested task list capabilities.
To better understand the fundamentals of Markdown you can reference the Markdown Cheatsheet or Markdown Basics.
Does anyone use GitHub Flavored Markdown?
Marie Dodson is an editorial assistant at Torque. She graduated from Cornell University with a degree in Biology and Society. She enjoys wine, good books, and travel.
Join the conversation