Markdown Text Formatting: Syntax Basics Explained
If you've written a README on GitHub, submitted a PR, or contributed to an open-source project, you've already used Markdown. It's everywhere — for good reason.
Markdown is a lightweight markup language for adding formatting to plaintext documents. John Gruber created it in 2004, and it's since become one of the most widely used markup languages around.
Unlike WYSIWYG editors that hide formatting behind a visual layer, Markdown uses simple symbols to indicate structure. Files stay readable as plain text — no proprietary formats, no binary blobs.
Why Markdown Took Over Developer Docs
Markdown documents are human-readable before they're rendered. Markdown processors output semantic HTML, files use standard text encoding, and they open in any editor on any OS.
Then there's the Git angle. Plain text works beautifully with version control, letting teams track changes line by line — a real advantage when reviewing a PR and you want to see exactly what changed in the docs.
Basic syntax clicks in a few hours, and that knowledge transfers across platforms: technical docs, blog posts, presentations, meeting notes.
The Core Markdown Text Formatting Syntax
Headings
Add # signs before a word or phrase. More signs = lower heading level.
# H1 — Page Title
## H2 — Major Section
### H3 — Subsection
One H1 per document. H2 for major sections, H3 for subsections. Good for reader orientation, SEO, and auto-generated tables of contents.
Bold and Italic
Two asterisks for bold, one for italic, three for both.
**This is bold**
*This is italic*
***This is both***
Lists
Ordered lists use numbers followed by periods. Unordered lists use hyphens. Indent to nest.
1. Clone the repo
2. Install dependencies
3. Run tests
- Feature flags
- CI pipeline config
- Deployment scripts
Code — Inline and Block
Backticks for inline code, triple backticks for multiline blocks. Add the language name after the opening backticks for syntax highlighting.
Run `npm install` before starting the server.
```javascript
function greet(name) {
return `Hello, ${name}`;
}
### Links and Images
```markdown
[Read the Docs](https://readthedocs.org)
Blockquotes
> Documentation is a love letter you write to your future self.
Tables (Extended Syntax)
Three or more hyphens create column headers; pipes separate columns.
| Syntax | Description |
| ------------ | ----------- |
| `**text**` | Bold |
| `*text*` | Italic |
| `` `code` `` | Inline code |
Tables, syntax highlighting, footnotes, and URL auto-linking are all extended syntax — not part of the original spec.