✨Dive into Markdown Magic!

Have you ever admired a beautifully crafted README, a polished Issue description or wonderfully formatted content right here on Dev.to and wished you could do the same? Now’s your chance to learn how! 💻📝

What is Markdown, You Ask?🤔

Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
John Gruber created Markdown in 2004 in collaboration with Aaron Swartz as an easy-to-read markup language.
Markdown is widely used for blogging and instant messaging, and elsewhere in online forums, collaborative software i.e. GitHub, documentation pages and README files.

Why Markdown?💡

Markdown is a sleek, powerful tool for content editing and it's the go-to standard for platforms like GitHub. Its versatility spans across various editors, both in browsers and clients.

While HTML is great for rendering content exactly how it was intended, it takes up a lot of space and can be hard to work with, even in small doses. The invention of Markdown offered a great compromise between the power of HTML for content description and the ease of plain text for editing.

Markdown Syntax

1. Emphasize Text

Create bold text by using two asterisks (**) or two underscores (__).

Markdown for bold text:
This is **bold** text.
This is also __bold__ text.

Result:

This is bold text.
This is also bold text.

Create italic text by using single asterisks * or single underscores _.

Markdown for italic text:
This is *italic* text.
This is also _italic_ text.

Result:

This is italic text.
This is also italic text.

Create strike through text using double tildes ~~.

Markdown for strike through text:
~~Strike through~~

Result:
Strike through

Create a horizontal rule using ---, ___ or ***.

Markdown for a horizontal rule:

---

Result:

To use a literal asterisk, precede it with a backslash (). This example results in the underscores and asterisks being shown in the output.

\_This is all \*\*plain\*\* text\_.

Result:

_This is all **plain** text_.

2. Quote text

You can create blockquotes using the greater than > character.

Markdown for quoted text:
> This is quoted text.

Result:

This is quoted text.

3. Code

Use a single backtick ` for single line code and three backticks ` for a code block.

Markdown for single line code:

Result:

This is code.

Markdown for a code block:

Result:
`markdown
var first = 1;
var second = 2;
var sum = first + second;
`

4. HTML additions

If you come across an HTML scenario not supported by Markdown, you can use that HTML inline.

Markdown using HTML:
Here is a<br />line break

Result:

Here is a
line break

5. Headings

These are quite similar with HTML headings, such as the <h1> tag.
You can also place an equal sign = underneath a title for a Headline level 1 and a hyphen - for a Headline level 2.

# - Headline level 1 (Biggest)
## - Headline level 2
### - Headline level 3
#### - Headline level 4
##### - Headline level 5
###### - Headline level 6 (Smallest)

6. Lists

You can define ordered or unordered lists. You can also define nested items through indentation.

• Ordered lists start with numbers.
• Unordered lists start with Hyphens -, Asterisks * or plus signs +.

Markdown for an unordered list:
`

• First
• Nested
• Second
• Third `

Result:

• First
• Nested
• Second
• Third

Markdown for an ordered list:
`

1. First
2. Second
3. Third `

Result:

1. First
2. Second
3. Third

7. Links

You can create a link by placing the link name inside square brackets []and then right next to that add the actual link inside parenthesis ()
Image and site links use a similar syntax

Markdown for a site link:
[Microsoft Learn](https://learn.microsoft.com/en-us/?wt.mc_id=studentamb_201445)

Result:

Microsoft Learn

Markdown for an image link:
![Link an image.](https://learn.com/azure-devops/shared/media/mara.png)

Result:

Variants🔀

Websites like GitHub, Reddit and Stack Exchange use variants of Markdown to make discussions between users easier.

In this blog post we will focus on GitHub Flavored Markdown or GFM as it's sometimes referred to.

GitHub Flavored Markdown

Overtime, GitHub has added improvements to the main markdown language so much so that this enhanced version is known as GitHub Flavor Markdown (GFM)
GFM is only supported on GitHub and extends Markdown's capabilities to support the following additional features:

1. Tables

By default, the columns are going to left align.
:----: will align the column at the center and ----: will align the column to the right
Below is some syntax for a table with 3 columns and 3 rows.
`
| Header | Header | Header |
|--------|--------|--------|
| Cell | Cell | Cell |
| Cell | Cell | Cell |
| Cell | Cell | Cell |
`

Result:

Header	Header	Header
Cell	Cell	Cell
Cell	Cell	Cell
Cell	Cell	Cell

2. Task List

This is a checklist
The x between the square brackets is for a checked task and the space is for an unchecked box.
Below is some syntax:
`

• [x] First
  • [x] One
  • [x] Two
• [ ] Second
• [ ] Third `

Result:

3. Alert Syntax

Below is the syntax and the equivalent output:
`

[!NOTE]
A note.

[!IMPORTANT]
Something important.

[!WARNING]
A warning.
`

Result:

4. Special Additions

You can drag, drop or paste the following file formats: .png, .gif, .jpg, .jpeg, .svg, .log, .docx, .pptx., .xlsx, .txt, .pdf, .zip, .gz, .mp4, .mov, .webm, .tgz. These components though have a size limit of 50 mb.

# in issues, discussions, and pull requests will let you refer to another issue and @ will pull up the names of people on your projects.

In pull requests, issues and discussions, you can also refer to:

• colors (rgb, hex, hsl) e.g. fb10cd2
• Emojis starting with : e.g. :t-rex
• Escape with **

5.Syntax Highlighting for popular languages

Just format a code block as you would using three backticks, but on the opening backticks, specify the language used in the code block.
Specifying the language will add the syntax highlighting feature.

Without Syntax Highlighting

Result:

With Syntax Highlighting

Result:

6. Slash Commands

Use slash commands to save time by reducing the typing required to create complex markdown.
You can use slash commands in any description or comment field in issues, pull requests or discussions where that slash command is supported.

Examples

/code -> Inserts a markdown code block. You choose the language.
/details -> Inserts a collapsible detail area. You choose the title and content.
/table -> Inserts a markdown table. You choose the number of columns and rows.
/tasklist -> Inserts a task list. This command only works in an issue description.
/saved-replies -> Inserts a saved reply. You choose from the saved replies for your user account.
/template -> Shows all of the templates in the repository. This command works for issue templates and pull request templates.

Conclusion

As the demand for high-quality, well-structured documentation continues to grow, Markdown offers a powerful solution. It not only enhances the quality of your documentation but also make the writing process more efficient and enjoyable.

For student developers and content creators, embracing the use of Markdown can significantly improve your productivity and the overall quality of your work.

Ready to take your Markdown documentation to the next level? Start by exploring this Microsoft Learn course and practice your learnings by taking this exercise on GitHub.

Next Up

This is the first off a 5-part blog series, recurring monthly, where we’ll explore GitHub like never before. Each post will build on the last, aiming to equip you with a profound understanding of GitHub, supercharging your project efficiency and collaboration skills.💪

In the next blog post, we will delve into GitHub Issues.
See you then!