DEV Community

Ragul
Ragul

Posted on

Markdown( .md) file

#markdown #github #developers #obsidian

If you've ever seen a file named README.md on GitHub, or noticed text with weird **stars** and # symbols, you've run into Markdown. This guide explains what it is, why people use it, and how to write it — in plain, simple terms.

Table of Contents

  1. What Is Markdown?
  2. Why Do People Use It?
  3. Headings
  4. Bold and Italic Text
  5. Lists
  6. Links
  7. Images
  8. Code
  9. Blockquotes
  10. Tables
  11. Horizontal Line
  12. Line Breaks (a Common Gotcha)
  13. Where Markdown Is Used
  14. Quick Summary

1. What Is Markdown?

Markdown is a simple way to format text using plain symbols, instead of clicking buttons like "Bold" or "Bullet List" in a word processor.

You type something like this:

# Hello World
This is **bold** and this is *italic*.
Enter fullscreen mode Exit fullscreen mode

And it turns into this when it's rendered (displayed nicely):

Hello World

This is bold and this is italic.

The file itself is just a plain text file — nothing fancy — saved with a .md extension (short for "Markdown"). You can open it in Notepad, VS Code, or any text editor, and it'll still make sense even unformatted, because the symbols are simple and readable on their own.

2. Why Do People Use It?

  • It's simple. You don't need any special software — just a text editor.
  • It's readable even as plain text. A .md file looks fine even before it's turned into a nicely styled page.
  • It's everywhere. GitHub, GitLab, Notion, Reddit, Discord, and countless apps understand Markdown.
  • It's fast to write. No mouse clicks — just type symbols as you go.

That's why documentation files, blog posts (like this one!), and README files are almost always written in Markdown.

3. Headings

Use the # symbol to make headings. The number of # symbols controls the size — one # is the biggest heading, and it gets smaller from there.

# Heading 1 (biggest)
## Heading 2
### Heading 3
#### Heading 4 (smallest commonly used)
Enter fullscreen mode Exit fullscreen mode

Renders as:

Heading 1 (biggest)

Heading 2

Heading 3

Heading 4 (smallest commonly used)

Tip: Always leave a space after the # symbols, or it won't work.

4. Bold and Italic Text 

This is **bold text**.
This is *italic text*.
This is ***bold and italic***.
Enter fullscreen mode Exit fullscreen mode

Renders as:

This is bold text.
This is italic text.
This is bold and italic.

You can also use __double underscores__ for bold and _single underscores_ for italic — they work the same way. Most people stick to asterisks (*) since it's more common.

5. Lists

Bullet list — use a dash, star, or plus sign:

- Apples
- Bananas
- Oranges
Enter fullscreen mode Exit fullscreen mode

Renders as:

  • Apples
  • Bananas
  • Oranges

Numbered list — use numbers followed by a period:

1. Wake up
2. Make coffee
3. Write code
Enter fullscreen mode Exit fullscreen mode

Renders as:

  1. Wake up
  2. Make coffee
  3. Write code

Tip: You don't need to get the numbers exactly right — Markdown will re-number them for you automatically. Typing 1. three times in a row still produces 1, 2, 3.

6. Links 

[Click here to visit Google](https://www.google.com)
Enter fullscreen mode Exit fullscreen mode

Renders as:

Click here to visit Google

The pattern is always: square brackets for the text people see, then parentheses right after for the actual web address — no space in between.

[text people see](https://the-actual-link.com)
Enter fullscreen mode Exit fullscreen mode

7. Images

Images work almost exactly like links, but with an ! in front:

![A cute dog](https://example.com/dog.jpg)
Enter fullscreen mode Exit fullscreen mode

The text inside the square brackets (A cute dog) is the "alt text" — a short description shown if the image can't load, and used by screen readers for accessibility.

8. Code

Inline code (for a single word or short snippet) — wrap it in single backticks:

Use the `console.log()` function to print something.
Enter fullscreen mode Exit fullscreen mode

Renders as:

Use the console.log() function to print something.

Code blocks (for multiple lines of code) — wrap the whole block in three backticks, with the language name right after the first set of backticks:

```javascript
function greet(name) {
  console.log("Hello, " + name);
}
```
Enter fullscreen mode Exit fullscreen mode

Renders as:

function greet(name) {
  console.log("Hello, " + name);
}
Enter fullscreen mode Exit fullscreen mode

Adding the language name (like javascript, python, or html) after the first three backticks tells Markdown to add color-coded syntax highlighting.

9. Blockquotes

Use > at the start of a line to quote something:

> This is a quote.
> It can span multiple lines.
Enter fullscreen mode Exit fullscreen mode

Renders as:

This is a quote.
It can span multiple lines.

This is commonly used to highlight a note, a quote from someone, or a warning.

10. Tables

Tables use pipes (|) to separate columns and dashes (-) to separate the header row from the data:

| Name  | Age | City     |
|-------|-----|----------|
| Sam   | 25  | Boston   |
| Alex  | 30  | New York |
Enter fullscreen mode Exit fullscreen mode

Renders as:

Name Age City
Sam 25 Boston
Alex 30 New York

Tip: The dashes don't need to line up perfectly — even |-|-|-| works. Markdown figures out the columns from the pipes.

11. Horizontal Line

Three or more dashes (or asterisks) on their own line create a horizontal divider:

---
Enter fullscreen mode Exit fullscreen mode

Renders as a line separating sections — useful for splitting up parts of a long document (you've seen several of these already in this post).

12. Line Breaks (a Common Gotcha)

This trips up almost everyone starting out: pressing Enter once in Markdown does not create a new line when rendered.

This is line one.
This is line two.
Enter fullscreen mode Exit fullscreen mode

Renders as:

This is line one.
This is line two.

(They get squished onto one line!)

To force a real line break, either:

  • Leave a completely empty line between them (this starts a new paragraph), or
  • Add two spaces at the end of a line before pressing Enter. 
This is line one.

This is line two.
Enter fullscreen mode Exit fullscreen mode

This renders as two separate paragraphs, properly spaced apart.

13. Where Markdown Is Used

  • GitHub / GitLab — README files, issues, pull request descriptions
  • Documentation sites — many docs are written and generated from .md files
  • Note-taking apps — Notion, Obsidian, and many others support Markdown
  • Chat apps — Discord and Slack use a simplified version of Markdown for bold/italic/code formatting
  • Blogging platforms — many static site generators (like Jekyll or Hugo) build entire websites from .md files

14. Quick Summary

What you type What you get
# Text Heading
**Text** Bold
*Text* Italic
- Text Bullet point
1. Text Numbered item
[Text](url) Link
![Alt](url) Image
`Text` Inline code


```code```

| Code block |
| > Text | Blockquote |
| \| col \| col \| | Table |
| --- | Horizontal line |

The big idea: Markdown lets you format text using a handful of simple, memorable symbols — no toolbar, no mouse, no fuss. Once you learn the dozen or so symbols in the table above, you can write clean, formatted documents anywhere Markdown is supported.

Top comments (0)