The plain-text formatting syntax behind READMEs, docs, and blog posts
Markdown is a lightweight syntax for formatting plain text that renders into HTML — bold, italics, headers, lists, links, code blocks — using symbols you can type on any keyboard without a mouse or a formatting toolbar. It became the default writing format for README files, documentation, blog posts, chat apps, and note-taking tools because it hits a rare balance: expressive enough for real formatting needs, but readable even in its raw, unrendered form.
# Heading 1 ## Heading 2 ### Heading 3
*italic* or _italic_ **bold** or __bold__ ***bold italic***
- Unordered item - Another item - Nested item 1. Ordered item 2. Another item
[Link text](https://example.com) 
Inline code uses single backticks: `code`. Multi-line code blocks use triple backticks, optionally followed by a language name for syntax highlighting:
```javascript
function hello() {
console.log("hi");
}
```
Tables use pipes and hyphens:
| Name | Role | |-------|-----------| | Alice | Engineer | | Bob | Designer |
The hyphen row separates the header from the body and, depending on colon placement (:---, :---:, ---:), controls column alignment in most renderers.
A > at the start of a line creates a blockquote, commonly used for highlighting a quotation or a note. Three or more hyphens, asterisks, or underscores on their own line (---) render as a horizontal divider line.
Markdown was never formally standardized by its original creator, which led to years of subtly incompatible implementations. Two specs dominate today:
~~text~~), task lists (- [ ] todo), and automatic URL linkingThe practical implication: a Markdown file with a table or a checkbox list may render correctly on GitHub but fail to render those elements on a stricter CommonMark-only renderer, since tables and task lists aren't part of the base spec.
\*) if it isn't meant to trigger emphasisBecause Markdown renders differently depending on the exact parser and flavor in use, previewing your document before publishing catches problems a raw text view can't — a table that silently didn't render as a table, a nested list that collapsed to the wrong indentation level, or a code block that lost its language-specific syntax highlighting. This matters most for anything going into a README, documentation site, or blog post where formatting errors are visible to readers rather than just yourself.
Does Markdown support footnotes? Not in base CommonMark, though several popular extensions and renderers (including many static site generators) add footnote syntax as a non-standard extension.
Can I nest a code block inside a list item? Yes, but it requires consistent indentation matching the list item's content — inconsistent indentation is the most common reason a code block inside a list renders incorrectly.
Why do the same tables look different on different sites? Table syntax comes from GitHub Flavored Markdown, not base CommonMark, so a site using a stricter or different renderer may not support it identically, or at all.
Two GFM extensions show up constantly in project management contexts. Task lists render as interactive checkboxes:
- [x] Completed task - [ ] Pending task
These are common in GitHub issues and pull request descriptions, where checking a rendered box actually updates the underlying Markdown source. Strikethrough text uses double tildes: ~~this is struck through~~, commonly used to mark something as outdated or superseded without deleting it entirely from the document.
This ubiquity is exactly why Markdown skills transfer so well — the same header, list, and code block syntax works nearly identically whether you're writing a GitHub README or a blog post.
Use the DataBench Markdown Live Preview to write Markdown and see exactly how it renders — headers, tables, code blocks, and more — right in your browser as you type.