Markdown Editor: How It Works
Markdown lets you write formatted text in plain characters, so the source stays readable and the output stays consistent. It is the format behind README files, documentation sites, static blogs and most developer note-taking — and it takes about ten minutes to learn completely.
The syntax
| Write | Get |
|---|---|
# Heading 1 … ###### Heading 6 | Headings |
**bold** · *italic* · ~~strike~~ | Emphasis |
[text](https://url) | Link |
 | Image |
- item or 1. item | Lists |
> quoted | Blockquote |
`code` or triple backticks | Inline and block code |
--- | Horizontal rule |
Two rules cause most confusion. A line break needs either two trailing spaces or a blank line — a single newline is treated as a continuation of the same paragraph. And nested list indentation must be consistent, conventionally two or four spaces, applied the same way throughout.
Flavours differ
There is no single Markdown. The original 2004 specification left many cases undefined, so implementations diverged.
| Flavour | Adds |
|---|---|
| CommonMark | A strict specification resolving the original ambiguities |
| GitHub Flavored Markdown | Tables, task lists, strikethrough, autolinks, fenced code with syntax names |
| MultiMarkdown | Footnotes, citations, definition lists |
| MDX | Embedded JSX components |
Tables are the practical trap: they are not in the original specification, so a table that renders on GitHub may appear as raw pipes elsewhere. Check what your target platform supports before relying on an extension.
Front matter
Static site generators read a YAML block at the top of a file, delimited by triple dashes, for metadata such as title, date, tags and layout. It is not part of Markdown itself, which is why it sometimes appears as visible text in tools that do not expect it.
Writing a README worth reading
- What it is, in one sentence, before anything else.
- A screenshot or example output if there is anything visual.
- Installation — the exact commands, copy-pasteable.
- Usage — the simplest example that does something real.
- Configuration, if any.
- Licence and contribution notes.
The most common failure is a README that explains the philosophy before saying what the software does. A stranger should know whether the project is relevant to them within thirty seconds.
Why Markdown rather than a word processor
- Plain text — diffs work, version control works, and the file is readable in fifty years.
- Portable — no proprietary format, no lock-in.
- Fast — no reaching for the mouse to apply formatting.
- Consistent — the rendering is decided by a stylesheet, not by whoever typed it.
Its limits are real: complex layout, precise typography and anything involving positioned elements are outside its scope. It is a format for structured prose, and it is excellent within that boundary.