How to Preview Markdown Online:
Step-by-Step Tutorial

This tutorial shows you how to preview Markdown as rendered HTML while you write it — for a README, a blog post, or documentation — and how to catch the formatting mistakes that only show up on render. You'll be previewing within thirty seconds; the rest is knowing what to look for.

Step 1: Paste or Write Your Markdown

Open the Markdown Preview and put your Markdown in the input panel. Start from an existing file (paste your README.md) or draft from scratch. A representative snippet:

# Project Name

A one-line description of what this does.

## Install

```bash
npm install project-name
```

## Usage

| Option | Default | Description |
|--------|---------|-------------|
| `--verbose` | false | Print debug output |

- Supports **Node 18+**
- MIT [license](LICENSE)

Everything renders locally in your browser — drafts never leave your machine, so previewing internal docs is safe.

Step 2: Read the Rendered Output Side by Side

The preview pane updates as you type. This live loop is the entire value of the tool: Markdown's failure mode is silent — broken syntax doesn't error, it just renders as literal text. Things to verify visually:

• Headings actually render as headings (a missing space after # is the classic silent failure — #Title renders as plain text, # Title renders as an h1).
• The code block is fenced correctly and shows its language highlighting.
• The table has rendered as a table, not as a row of pipe characters.
• Links resolve to the text you intended, with no stray brackets left visible.

Step 3: Fix What Rendered Wrong

The most common silent failures, and their one-character fixes:

You typed	What renders	Fix
#Heading	Literal "#Heading" text	Space after #: # Heading
*item (no space)	Literal asterisk	* item or - item
List right after a paragraph	Runs into the paragraph	Blank line before the list
[text] (url)	Brackets shown literally	No space: [text](url)
Table without --- row	Pipes as plain text	Add separator: |---|---|
4-space indented code	Unexpected code block	Un-indent, or use fenced ``` blocks

The blank-line rule causes the most confusion: Markdown treats a list, blockquote, or heading that directly follows a text line as part of the same paragraph. When something "refuses" to render, add a blank line above it first — that fixes it more often than anything else.

Worked Example: Cleaning Up a README Before Pushing

1. Paste your draft README into the preview. Immediately visible: the Install section's code block swallowed the Usage heading — the closing fence line was `` (two backticks, a typo) so the block never ended.
2. Fix the fence to three backticks. Now the table renders as pipes and dashes — the separator row is missing a column: 3 columns declared in the header, 2 in the separator.
3. Add the third --- cell. Table renders. Last check: the license link [license](LICENSE) will only work on GitHub if the LICENSE file exists at repo root — the preview can't verify the target, so check that manually.
4. Copy the corrected Markdown back to your editor and commit. Total time: two minutes, zero broken-formatting commits pushed.

Previewing Markdown Without the Tool

• VS Code: Cmd/Ctrl+Shift+V opens a preview tab; Cmd/Ctrl+K V opens it side by side. Uses the same CommonMark core as most renderers.
• GitHub: editing any .md file in the web UI gives you a Preview tab — the definitive check for GitHub-flavored specifics.
• Command line: pandoc README.md -o preview.html && open preview.html, or grip README.md (a Python tool that renders through GitHub's own API, catching GFM edge cases exactly).

The browser tool wins when you're not at your own machine, when the Markdown lives in a CMS or chat message rather than a file, or when you want a scratchpad that doesn't touch the repo.

Common Problems and Fixes

It renders here but looks different on GitHub

Markdown has dialects. Core CommonMark is universal, but tables, task lists (- [x]), strikethrough (~~text~~), and auto-linked URLs are GitHub Flavored Markdown (GFM) extensions — support varies across renderers (GitLab, npm, static site generators, chat apps). If a feature matters, test in the destination renderer; treat this preview as the CommonMark+GFM baseline.

HTML tags in my Markdown disappear

Markdown permits inline HTML, but most platforms sanitize it — GitHub strips <script>, <style>, and most attributes. If your layout depends on raw HTML, expect it to survive only on renderers you control. For a pure-HTML scratchpad, use the HTML Preview instead.

Line breaks don't appear where I typed them

A single newline inside a paragraph is joined, not broken — that's per spec. Force a break with two trailing spaces at the end of the line, a backslash at the end, or a full blank line for a new paragraph. (Some renderers, like GitHub comments, break on single newlines anyway — another dialect difference.)

Special characters trigger formatting I didn't want

Asterisks in "2 * 3 * 4" can italicize unexpectedly; underscores in snake_case_names likewise. Escape with a backslash (\*, \_) or wrap the term in backticks — inline code disables all formatting inside it.

FAQ

What's the difference between Markdown and HTML?

Markdown is a shorthand that compiles to HTML — **bold** becomes <strong>bold</strong>. It covers the common 90% of document structure with far less typing; for the remaining 10% (custom classes, embeds, precise layout) you drop into inline HTML, subject to the sanitization limits above.

Which Markdown flavor should I write in?

CommonMark + GFM tables and task lists is the pragmatic default — it renders correctly on GitHub, GitLab, VS Code, and most documentation systems. Avoid renderer-specific extensions (footnotes, definition lists, admonitions) unless you know every destination supports them.

Can I convert Markdown to HTML for my website?

Yes — every static site generator (Astro, Hugo, Jekyll, Eleventy) does it at build time, and libraries like marked or markdown-it do it at runtime. For a one-off conversion, pandoc file.md -o file.html handles it, including full standalone documents with --standalone.

Why do my README badges/images not show in the preview?

Relative image paths (![logo](./docs/logo.png)) resolve against the repo on GitHub but point nowhere from a browser tool. Absolute URLs render fine. This is expected — verify relative-path images in the GitHub preview instead.