DEV Community

Pasindu Balasooriya
Pasindu Balasooriya

Posted on Originally published at Medium on

Markdown is the quietly powerful language you already almost know

#markdown #md


https://serokell.io/blog/markdown-editor-tips

You have probably written Markdown without realizing it. That asterisk you typed around a word in a Slack message to make it bold? Markdown. The hash symbol you threw before a heading in a README? Also Markdown. It is one of those rare tools that feels natural before you even learn it properly.

This article is a complete guide to Markdown with what it is, why it matters and how to use it with real examples you can see rendered live.

What is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. The idea was simple. Write plain text that reads naturally and let a program convert it to formatted HTML. Instead of wrestling with

tags and wrappers, you write human-readable symbols that carry their own meaning.
## Hello, World

This is a **very** important message.

Same output. Far less noise.

Where Markdown is used

Markdown is everywhere once you start looking. GitHub uses it for README files, issues and pull requests. Medium supports Markdown imports and keyboard shortcuts that mirror it. Notion, Obsidian and Confluence all render Markdown natively. Reddit uses a Markdown dialect for post formatting. Static site generators like Jekyll and Hugo build entire websites from Markdown files.

Learning Markdown is a one-time investment that pays dividends across almost every platform a developer or writer touches.

The core syntax

Headings

Use the # symbol to create headings. The number of # symbols corresponds to the heading level, from H1 to H6.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Bold and italic

Wrap text in **double asterisks** for bold and *single asterisks* for italic. You can combine them.

This is **bold text**.
This is *italic text*.
This is ***bold and italic*** at the same time.

Lists

Unordered lists use -, * or + as bullet points. Ordered lists use numbers. You can nest lists by indenting with two or four spaces.

  1. Unordered 
- Milk
- Eggs
- Bread

  1. Ordered 
1. Clone the repository
2. Install dependencies
3. Run the dev server

  1. Nested 
- Frontend
  - React
  - Tailwind CSS
- Backend
  - Node.js
  - PostgreSQ

Links and images

Links follow the pattern link text. Images work the same way with an exclamation mark prepended. The text in square brackets becomes the alt text, which matters for accessibility.

Read the [Markdown Guide](https://www.markdownguide.org) for more.

Code

For inline code, wrap it in backticks. For code blocks, use triple backticks and optionally specify the language for syntax highlighting.

  1. Inline code 
Use the `console.log()` function to debug.

  1. Code block


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


plaintext

Tables

Tables use pipes | and hyphens - to define structure. The second row separates the header from the body. You can align columns by adding colons to the separator row.

  1. Basic table 
| Name | Role | Status |
|------------|--------------|----------|
| Alice | Developer | Active |
| Bob | Designer | Active |
| Carol | QA Engineer | On leave |


plaintext

  1. With alignment 
| Left | Center | Right |
|:-----------|:------------:|---------:|
| aligned | aligned | aligned |


plaintext

Task lists

GitHub Flavored Markdown adds interactive checkboxes using - [x] for checked and - [] for unchecked items.

- [x] Set up the project
- [x] Write the README
- [] Add unit tests
- [] Deploy to production


plaintext

A common mistake: escaping special characters

What if you actually want to display an asterisk without triggering bold formatting? Use a backslash to escape it. The same trick works for #, [,], (, ) and other Markdown-reserved characters.

This is \*not bold\*.


plaintext

A real-world example: a project README

Here is what a solid Markdown README looks like in practice. This is entirely plain text. No Word document, no HTML, no design tool. Just a .md file that renders beautifully on GitHub.

# MyApp

A lightweight REST API for managing personal tasks.

## Features

- Create, update, and delete tasks
- Assign due dates and priority levels
- Filter tasks by status

## Getting Started

### Prerequisites

- Node.js 18+
- PostgreSQL 14+

### Installation

1. Clone the repository:


bash
git clone https://github.com/yourname/myapp.git

2. Install dependencies: `npm install`
3. Create a `.env` file based on `.env.example`.
4. Start the server: `npm run dev`

## License

MIT

Why Markdown beats rich text editors

Rich text editors hide their formatting inside binary or XML structures you cannot read or version-control easily. Markdown files are plain text, which means:

Version control works perfectly.

Git can diff a .md file line by line and show exactly what changed. Try doing that with a .docx.

They are portable.

A Markdown file opened in 2040 will look exactly the same as it does today. File formats rot. Plain text does not.

They are distraction-free.

You are not hunting through toolbar menus. The formatting lives in the text itself, which keeps you focused on writing.

They convert to almost anything.

With tools like Pandoc, a single Markdown file can become a PDF, an HTML page, a Word document or an ePub.

Getting started today

You do not need to install anything. Open StackEdit or Dillinger in your browser. Type some Markdown on the left and watch it render on the right in real time.

If you use VS Code, the built-in Markdown preview (Ctrl+Shift+V) is excellent. If you want a dedicated writing environment, Obsidian and Typora are both popular choices.

The learning curve is genuinely shallow. Most people feel comfortable with the core syntax within an afternoon. What you get in return is a formatting language that works everywhere, lasts forever and never gets in your way.

Start with a README for your next project. That is all it takes.

Top comments (0)