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.
Example:
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).
Instructions
Create the Markdown File
- On your repository home page, click Add File, then Create New File.
- 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 List | 1. 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
- A general guide to Markdown symbols (not tied to any particular platform)
- A further explanation of Docs as Code
- Writing with GitHub (GitHub-specific Markdown)
- Setting up a GitHub account + other useful information