What is Markdown and How to Use It?

Markdown is a lightweight markup language that allows you to create formatted text using a plain-text editor. Originally created by John Gruber in 2004, Markdown is widely used for documentation, blogging, note-taking, and even content formatting in websites and applications.

In this article, we’ll cover what Markdown is, where it’s commonly used, and how to apply its most essential formatting features.

What is Markdown?

Markdown is a simple way to style text on the web. Instead of using complex HTML tags or WYSIWYG editors, Markdown allows users to write using a readable, plain-text syntax which then gets converted to HTML.

For example, to make text bold, you simply wrap it in double asterisks like **this**, and to create a list, you can use dashes or numbers.

Markdown is popular for its balance of simplicity and flexibility, making it accessible for both technical and non-technical users.

Common Use Cases of Markdown

Markdown is used in many places where plain text needs to be styled or structured.

Technical Documentation

Developers and technical writers often use Markdown to write documentation because of its readability and easy integration with version control systems like Git.

README Files in GitHub

GitHub supports Markdown natively for README files and documentation. It’s the default format to introduce and explain a project.

Blogging and Content Writing

Many modern static site generators like Jekyll, Hugo, and Next.js support Markdown for content creation. It’s also used by blogging platforms like Ghost and Dev.to.

Note-taking Apps

Apps like Obsidian, Notion (partial support), and Bear allow users to write notes using Markdown syntax for easy formatting.

Email Formatting and Messaging

Some email clients and messaging platforms (like Slack and Discord) allow partial Markdown syntax for basic formatting like bold, italics, or code blocks.

Basic Markdown Syntax and How to Use It

Markdown syntax is straightforward and human-readable. Here are the most common elements you’ll need.

Headings

Use # symbols to create headings. The number of # symbols corresponds to the heading level.

# H1 - Main Title
## H2 - Section Title
### H3 - Subsection Title

Emphasis

You can emphasize text with italics or bold:

*Italic text* or _Italic text_
**Bold text** or __Bold text__
***Bold and italic*** or ___Bold and italic___

Lists

Markdown supports both unordered and ordered lists.

Unordered list:
```
- Item 1
- Item 2
  - Sub-item
```

Ordered list:

1. First item
2. Second item
   1. Nested item

Links

To add a hyperlink, use square brackets for the text and parentheses for the URL:

[Visit OpenAI](https://www.openai.com)

Images

Images use the same syntax as links but start with an exclamation mark:

![Alt text](https://example.com/image.png)

Blockquotes

To create a blockquote, prefix the line with >:

> This is a blockquote.

Code and Code Blocks

For inline code, wrap the text with backticks:

Use the `console.log()` function.

For multi-line code blocks, use triple backticks:

```javascript
function greet(name) {
  return `Hello, ${name}`;
}
```

Horizontal Rule

Use three or more dashes, asterisks, or underscores to create a horizontal line:

---

Tables

Markdown tables use pipes and hyphens:

| Syntax | Description |
|--------|-------------|
| Header | Title       |
| Cell   | Content     |

Tips for Writing in Markdown

Use a Markdown preview tool (like VS Code, Typora, or StackEdit) to instantly view the output.
When writing longer documents, organize your sections with proper headings.
Use consistent formatting to maintain clarity.
Use comments (HTML-style ) to leave notes that won’t appear in the final output.