GitHub Flavored Markdown, often abbreviated as GFM, is a variant of the standard Markdown language that is tailored to the specific needs and environment of GitHub. It is designed to simplify the process of formatting text on the web, making it easier for developers to create readable and aesthetically pleasing documentation for their projects.
Markdown, the language upon which GFM is based, was created by John Gruber and Aaron Swartz in 2004. It was designed to be an easy-to-read and easy-to-write plain text format, which could be converted into structurally valid HTML. GitHub Flavored Markdown extends this original specification with features designed to make it more useful for software development and collaboration.
Definition and Syntax of GitHub Flavored Markdown
The syntax of GitHub Flavored Markdown is a superset of the standard Markdown syntax. This means that any text formatted using standard Markdown syntax will also be correctly formatted in GFM. However, GFM also includes additional syntax elements that are not found in standard Markdown.
For example, GFM introduces syntax for creating tables, which is not present in standard Markdown. This syntax allows developers to create structured data in a tabular format, which can be very useful for presenting information in a clear and concise way. The syntax for creating a table in GFM is as follows:
Tables in GFM
To create a table in GFM, you use pipes (|) and hyphens (-) to define the structure of the table. The pipes are used to separate the columns of the table, and the hyphens are used to create the header row. For example, the following GFM syntax:
| Column 1 | Column 2 |
| --------- | --------- |
| Cell 1 | Cell 2 |
Would be rendered as a table with two columns and two rows, with the first row being the header row.
Task Lists in GFM
Another feature that GFM introduces is the ability to create task lists. This can be very useful for tracking progress on a project, or for creating to-do lists. The syntax for creating a task list in GFM is as follows:
- [ ] Task 1
- [x] Task 2
This would be rendered as a list with two items, the first of which is unchecked, and the second of which is checked.
Use Cases for GitHub Flavored Markdown
GitHub Flavored Markdown is primarily used for writing documentation on GitHub. This includes README files, which are used to provide an overview of a project and instructions for how to use or contribute to it, as well as issue and pull request descriptions, which are used to describe proposed changes to a project or problems that need to be addressed.
However, the use of GFM is not limited to GitHub. Many other platforms and tools that are used for software development and collaboration also support GFM, including Jekyll (a static site generator), Discourse (a platform for community discussions), and many others. This means that learning GFM can be beneficial not only for working with GitHub, but also for many other aspects of software development.
Writing README Files
One of the most common uses of GFM is for writing README files. A README file is a text file that is included in the root directory of a project, and it is typically the first thing that a person sees when they visit the project's GitHub page. The README file is used to provide an overview of the project, including a description of what the project does, how to install and use it, and how to contribute to it.
Because the README file is often the first point of contact between a project and a potential user or contributor, it is important that it is clear, concise, and well-formatted. GFM provides the tools to achieve this, allowing developers to create structured, readable text with headings, lists, links, code blocks, and more.
Writing Issue and Pull Request Descriptions
Another common use of GFM is for writing issue and pull request descriptions on GitHub. When a developer identifies a bug in a project, or proposes a change to the project's code, they can create an issue or a pull request to communicate this to the project's maintainers.
The description of the issue or pull request is used to provide a detailed explanation of the problem or proposed change, and it is important that this description is clear and easy to understand. GFM provides the tools to achieve this, allowing developers to create structured, readable text with headings, lists, links, code blocks, and more.
Specific Examples of GitHub Flavored Markdown
Now that we've covered the basics of what GitHub Flavored Markdown is and how it's used, let's take a look at some specific examples of GFM syntax and how it's rendered.
These examples will cover some of the most commonly used features of GFM, including headings, lists, links, code blocks, tables, and task lists. By studying these examples, you can get a better understanding of how to use GFM to create well-formatted, readable text.
Headings
In GFM, you can create headings by using one or more hash symbols (#) at the start of a line. The number of hash symbols determines the level of the heading, with one hash symbol for a first-level heading, two for a second-level heading, and so on up to six for a sixth-level heading.
For example, the following GFM syntax:
# Heading 1
## Heading 2
### Heading 3
Would be rendered as three headings, each with a different level.
Lists
In GFM, you can create lists by using either asterisks (*) or hyphens (-) at the start of a line. To create a numbered list, you can use numbers followed by a period (.) at the start of a line.
For example, the following GFM syntax:
* Item 1
* Item 2
* Item 3
Would be rendered as a bulleted list with three items.
Links
In GFM, you can create links by enclosing the link text in square brackets ([]), followed by the URL in parentheses (()).
For example, the following GFM syntax:
[Link Text](https://example.com)
Would be rendered as a link with the text "Link Text", which points to the URL "https://example.com".
Code Blocks
In GFM, you can create code blocks by enclosing the code in triple backticks (```). You can also specify the programming language for syntax highlighting by including it after the opening backticks.
For example, the following GFM syntax:
```python
def hello_world():
print("Hello, world!")
```
Would be rendered as a code block with Python syntax highlighting.
Conclusion
GitHub Flavored Markdown is a powerful tool for creating well-formatted, readable text on the web. Whether you're writing documentation for a project, describing an issue or a pull request, or just creating a post on a discussion forum, GFM can help you to communicate your ideas more effectively.
By learning the syntax and features of GFM, you can become a more effective communicator in the world of software development. So why not start practicing with GFM today?