Markdown Preview: Write and See Results in Real Time

Markdown is the lingua franca of developer documentation. README files, pull request descriptions, wiki pages, blog posts, and API docs all use Markdown. Its simplicity is its strength: you write in plain text, and a renderer produces formatted HTML. A real-time preview closes the feedback loop, letting you see the output as you type.

Core Markdown Syntax

The basics are deceptively simple. Here is a quick reference for the syntax you will use 90% of the time:

Headings

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

Use heading levels semantically. A document should have one # heading (the title), with ## for major sections and ### for subsections. Skipping levels (going from ## to ####) hurts accessibility and document outline clarity.

Text Formatting

**Bold text** for emphasis
*Italic text* for secondary emphasis
`inline code` for technical terms
~~Strikethrough~~ for corrections

Avoid using bold for entire paragraphs. Reserve it for key terms and important phrases within a sentence.

Links and Images

[Link text](https://example.com)
[Link with title](https://example.com "Hover text")

![Alt text](./image.png)
![Alt text](./image.png "Optional title")

Always include descriptive alt text for images. Screen readers depend on it, and it displays when images fail to load.

Code Blocks

Fenced code blocks with language identifiers enable syntax highlighting:

function greet(name) {

return Hello, ${name}!;

}

Supported languages vary by renderer, but common identifiers include javascript, typescript, python, bash, json, css, html, sql, and yaml.

Lists

- Unordered item
- Another item
  - Nested item

1. Ordered item
2. Second item
   1. Nested ordered item

Indent nested items by 2 or 3 spaces (depending on the renderer). Be consistent within a document.

Tables

| Column A | Column B | Column C |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Align columns with colons in the separator row:

| Left | Center | Right |
|:-----|:------:|------:|
| a    |   b    |     c |

Tables in Markdown are best for small datasets. For anything beyond 5-6 columns, consider linking to a spreadsheet or using an HTML table.

Blockquotes

> This is a blockquote.
> It can span multiple lines.
>
> And multiple paragraphs.

Use blockquotes for callouts, citations, or highlighting important notes.

GitHub-Flavored Markdown (GFM)

GitHub extends standard Markdown with several useful features:

Task Lists

- [x] Implement authentication
- [x] Write unit tests
- [ ] Deploy to staging
- [ ] Update documentation

These render as interactive checkboxes in GitHub issues and pull requests.

Alerts

> [!NOTE]
> This is additional context.

> [!WARNING]
> This could cause data loss.

> [!CAUTION]
> This action is irreversible.

GitHub renders these as colored callout boxes. They are excellent for drawing attention to important information in documentation.

Footnotes

This claim needs a source[^1].

[^1]: Source: https://example.com/research

Footnotes are useful for academic-style references without cluttering the main text.

Writing Documentation That Lasts

Good documentation follows predictable patterns:

Start with the problem. Before explaining how something works, explain why someone would need it. A README should answer "What does this do?" and "Why should I care?" before diving into installation instructions.

Show, then explain. Lead with a code example, then explain what it does. Developers scan for code blocks first.

## Quick Start

npm install my-library

import { transform } from "my-library";

const result = transform(input);

This installs the library and runs a basic transformation.

Keep paragraphs short. On screens, dense paragraphs are hard to scan. Aim for 2-4 sentences per paragraph. Use lists for anything with three or more items.

Use consistent terminology. If you call it a "workspace" in one section, do not call it a "project" in another. Create a glossary for complex domains.

Real-Time Preview Workflows

Writing Markdown without a preview is like writing CSS without a browser. You can do it, but feedback cycles are slow and errors accumulate.

Most code editors offer split-pane Markdown preview. VS Code has it built in (Ctrl+Shift+V or Cmd+Shift+V). This is sufficient for most editing.

For focused writing sessions, a dedicated Markdown editor with live preview removes distractions. The preview pane scrolls in sync with the editor, so you always see the output for the text you are currently editing.

Common Mistakes

1. Not escaping special characters. Characters like , _, #, and | have Markdown meaning. Escape them with a backslash when they appear in regular text: \not italic\*.
2. Missing blank lines. Most renderers require a blank line before headings, lists, and code blocks. Without it, the formatting may not apply.
3. Inconsistent list markers. Mixing -, *, and + within a single list works but looks sloppy. Pick one and stick with it.
4. Overusing HTML. Markdown supports inline HTML, but overusing it defeats the purpose. If you need complex layouts, consider a documentation framework like Docusaurus or Nextra.

Try our Markdown Preview to write and preview Markdown in real time — right in your browser, no upload required.