How to Create a Markdown File in Github

How to Create a Markdown File in Github

By Chantal Cyrier

Introduction to Markdown

Markdown is a markup language used in a plain text editor. It is often employed when using a documentation as code (docs as code) framework, which is a way of developing documentation that mirrors the workflows and tools used by software developers to write code. In a docs as code environment, the documentation is more fully integrated with the development team and their products, often making collaboration and organization easier. Markdown can also be used in many other contexts, as it is a lightweight, yet effective language.


This article will focus on how to create a Markdown file in GitHub, a cloud-based code development platform. These same principles for Markdown carry from platform to platform, but there can often be small differences, such as in formatting symbols used. In the steps below, it is assumed that you already have a GitHub account and a repository set up (for guidance on how to set this up, please see the Additional Resources at the end of this article).


Create the Markdown File

  1.  On your repository home page, click Add File, then Create New File.
  1. In the File Name field, type the name of your document, and then type “.md” at the end. 

Note: “.md” is the Markdown file extension that GitHub uses.

Write the Copy

In Markdown, plain text can be typed normally. Symbols are used before or before and after the affected text to denote formatting, which differs from the “clicking buttons” model of formatting used by traditional word processors, like Word. Some common symbols are listed below.

Headings# First Level Heading 
## Second Level Heading
###Third Level Heading
Bold**bold text**
__bold text__
Italic*italic text*
_italic text_
Bulleted List–        Item One
–        Item Two
–        Item Three

Can also use * or +
Numbered List1.      Item One
2.      Item Two
3.      Item Three
Horizontal Rule

Note: If you wish to check what your finished version will look like, click Preview, which is located to the right of Edit and below the File Name field.

Commit Changes

To save your document, click Commit Changes, then Commit Changes again.

Finished Product

The Markdown text written throughout these instructions is shown here as it would appear in the front end.

Pros and Cons of Markdown

Like any tool, Markdown has pros and cons. Among its pros is that it is relatively easy to write and read. In addition, since it uses written symbols, instead of clicking buttons, to format text, the workflow can be streamlined. However, Markdown is not standardized, meaning it can be awkward and time-consuming to move to a new platform. Since Markdown was first developed for blogging, rather than technical documentation, some advanced formatting features may be lacking. In addition, the inability to see what the finished product will look like during the writing process often presents a learning curve.

In all, despite its drawbacks, Markdown is a lightweight syntax that is easy to learn and implement, especially in an open-source platform like GitHub. While it can be used in other contexts, it is especially a good place to start if you are starting to delve into docs as code.

Additional Resources

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.