How to Work With GitHub Flavored Markdown in Linux?

Markdown is a popular lightweight markup language that allows users to write using an easy−to−read and easy−to−write plain text format, which can then be converted into HTML or other formats. In essence, it simplifies the process of structuring and formatting text. GitHub Flavored Markdown (GFM) is a variant of Markdown used by GitHub, incorporating additional features that help developers to document their work.

In this article, we're going to delve into how to work with GitHub Flavored Markdown on a Linux system, with practical examples and their output.

Basics of GitHub Flavored Markdown

Let's start with the basics of GFM.

Headers − You can create a header by using the '#' character followed by a space and the header text. The number of '#' characters used corresponds to the level of the header, from 1 (highest) to 6 (lowest). For example −

# Header 1
## Header 2
### Header 3

Emphasis − For emphasis, you can make text bold or italic. The syntax is quite straightforward −

*This text will be italic*
**This text will be bold**

Lists − You can create ordered and unordered lists using numbers or the '*' character respectively −

1. First item
2. Second item

* Item
* Another item

Links − To create a hyperlink, use square brackets for the link text and parentheses for the URL −

[GitHub](http://github.com)

Images − To insert an image, use an exclamation point (!), followed by alt text in square brackets and the URL or path of the image in parentheses:

![GitHub Logo](/images/logo.png)

Code − To insert code, use backticks (`). For inline code, use a single backtick, for blocks of code use three backticks −

`This is inline code`

This is a code block

# GitHub Flavored Markdown (GFM) Extras

While the above examples are common to all Markdown, GFM adds a few useful extras:

1. **Task Lists**: GFM introduces the concept of task lists. These are lists with checkboxes that can be ticked off.

```markdown
- [x] Completed task
- [ ] Incomplete task

Tables − GFM allows the creation of simple tables −

| Column 1 | Column 2 |
| -------- | -------- |
| Cell 1   | Cell 2   |

Syntax Highlighting − With GFM, you can specify the language for code blocks to enable syntax highlighting. For instance −

```python
def hello_world():
   print("Hello, world!")


# Viewing Your Markdown Files

To view your Markdown files on a Linux system, you'll need a Markdown viewer or use an online viewer. For local viewing, you can use applications like "ReText" or "Mark Text". To install ReText, for example, you can use the command:

```bash
sudo apt install retext

You can also use the grip utility to view your Markdown files in a web browser. It can be installed using pip −

pip install grip

Then, to view a file, navigate to the directory containing the file and run −

grip yourfile.md

Grip will render the Markdown file and you can view it by opening your web browser to localhost:6419.

More on GitHub Flavored Markdown

While we have already discussed the basic features and a few additional elements introduced by GFM, let's delve into some more useful features that make documentation and writing on GitHub a breeze.

Automatic linking for URLs − GFM treats URLs as links automatically, which is not the case in regular Markdown. It saves the time of wrapping URLs in []() to create a link.

http://www.github.com/

Strikethrough − GFM has added syntax to strike through text, which is not available in plain Markdown. This can be achieved by wrapping the text with double tildes ~~.

~~This text will be strikethrough~~

Emoji − GFM supports the use of shortcodes for emoji in the form :EMOJICODE:. GitHub maintains a full list of the emoji shortcodes they support here.

:smile:

Nested Lists − In GFM, you can nest one list under another by indenting the nested list with four spaces.

1. Item 1
    1. Sub Item 1
    2. Sub Item 2
2. Item 2

Referencing Issues and Pull Requests − Another feature of GFM is the ability to reference issues or pull requests directly using the '#' symbol followed by the issue or pull request number.

See #123 for more details.

User Mentions − GFM allows you to mention a user directly, similar to many social platforms, using the '@' symbol followed by the username.

Thanks for the contribution, @username!

Disabling Automatic URL Linking − If you want to mention a URL without it being automatically converted into a link, you can use backticks −

`http://www.github.com/`

More Markdown Editors

We've mentioned "ReText" and "Mark Text" as options for viewing your Markdown files. Other good alternatives to consider include −

• Typora − This is a versatile and stylish Markdown editor that supports the live preview of Markdown.

• Atom − Atom is a text editor developed by GitHub. It supports Markdown out of the box and can render your Markdown file in a split screen.

• Visual Studio Code − VS Code has built-in support for Markdown. It features a live preview function, and there are also numerous extensions available for added functionality.

• Ghostwriter − This is a distraction-free Markdown editor that features a clean, straightforward interface.

Advanced Features of GitHub Flavored Markdown

GitHub Flavored Markdown isn't limited to just the basics. It has a range of advanced features that can significantly enhance the quality of your text. Let's dive into these features:

Blockquotes − These can be used to highlight significant portions of text. You can create a blockquote by starting a line with the '>' character.

> This is a blockquote.

Inline HTML − If Markdown syntax doesn't quite cut it for you, GFM allows you to insert raw HTML into your documents.

<strong>This is bold text</strong>

Horizontal Lines − You can create a horizontal line by using three hyphens, asterisks, or underscores.

---
***
___

Escaping Characters − In Markdown, certain characters have special meanings. If you want to display these characters as they are, you can escape them with a backslash '' before the character.

\*This text will not be italic\*

Automatic Anchors − GFM automatically adds id attributes to your headers, which creates anchor links. This feature is especially handy when you're creating a table of contents or when you need to direct readers to a specific section of your document.

# Table of Contents
1. [Chapter 1](#chapter-1)
2. [Chapter 2](#chapter-2)

Advanced Markdown Tools in Linux

Here are a few more advanced tools for handling Markdown in Linux −

Pandoc − This is a versatile document converter. It can convert documents in Markdown, HTML, LaTeX and many other formats.

sudo apt-get install pandoc

Remark-lint − If you want to ensure your Markdown files adhere to a style guide, you can use Remark-lint, a pluggable Markdown linter written in JavaScript.

npm install remark-lint

Marp − Marp is a Markdown presentation writer with an easy-to-use CLI.

npm install --global @marp-team/marp-cli

Conclusion

In this article, we've covered the basics of using GitHub Flavored Markdown in Linux, with examples and explanations of each feature. GFM adds a few useful extras to the standard Markdown, making it an excellent choice for software documentation. Whether you're documenting your code or writing in a blog, Markdown can be a handy tool to have in your arsenal.