What Markdown is used for
Markdown is a lightweight markup language that turns plain text into formatted HTML using simple symbols: # for headings, * for emphasis, - for list items and backticks for code. It's the format behind README files, GitHub issues and pull requests, documentation sites, static-site blogs, chat apps, and note-taking tools like Obsidian.
This editor is for writing that source text. Headings, bold and italic text, links, list markers, block quotes and code spans each get their own colour, so a missing closing backtick or bracket stands out. Pressing Enter inside a list or quote continues it with the next marker (and numbers ordered lists for you), while Backspace removes an empty marker. You also get find and replace, word wrap (useful for long paragraphs), a dark theme, fullscreen, copy, and a download that saves README.md.
Be aware that there is no rendered preview. You see the Markdown, not the formatted page.
Example: release notes
Paste this into the editor:
# Release notes: v2.4.0
Released **5 October 2026**. Upgrade with `npm install mytool@2.4.0`.
## What changed
- Faster start-up on large projects
- New `--watch` flag
- restarts the process when files change
- Fixed a crash when `config_file_path` is empty
1. Back up your config.
1. Run the upgrade.
1. Restart the service.
> **Note:** the `--legacy` flag has been removed.
```bash
mytool --watch src/
```
See the [full changelog](https://example.com/changelog) for details.
Rendered by a CommonMark parser, the three 1. items come out numbered 1, 2, 3. The nested item becomes a sub-list because it's indented two spaces, to line up with the text of its parent item.
Markdown rules that cause surprises
Most rendering bugs come from a few rules in the CommonMark specification:
| You wrote | What happens | Fix |
|---|---|---|
| A sub-item indented by one space | It stays at the top level | Indent it to where the parent's text starts: 2 spaces after - , 3 after 1. |
| Two lines with a single newline between them | They join into one line of the same paragraph | End the first line with \ or two spaces for a line break, or leave a blank line for a new paragraph |
2*3*4 |
The 3 turns italic |
Escape the asterisks (2\*3\*4) or put it in a code span |
A list starting 3. straight after paragraph text |
It doesn't become a list | Leave a blank line before it; only a list starting at 1. can interrupt a paragraph |
snake_case_names |
Nothing (this one is safe) | Underscores inside a word never create emphasis, unlike asterisks |
Tables (| a | b |), task lists (- [ ] todo), strikethrough (~~old~~) and bare URLs turning into links come from the GitHub Flavored Markdown spec, not CommonMark itself. GitHub, GitLab and most documentation tools support them, but a strict CommonMark renderer will show the pipes and tildes as plain text.
Previewing your file
- Click Download. The file saves as
README.md; rename it if it isn't a readme. - Open it in VS Code and press
Ctrl+Shift+V(Cmd+Shift+Von macOS) for the built-in preview. - Or convert it from the command line with Pandoc:
pandoc README.md -o README.html. - For a README, committing it to a GitHub repository shows it rendered on the repository page.
Related tools
Check the length of a post with the word counter, rename terms across a document with find and replace, and if you need raw HTML instead, use the HTML editor. All languages are listed on the online code editors page.
Last updated