DEV Community

Cover image for Markdown Live Preview: 4 Ways to See What Your README Really Looks Like Before You Push
TypeFire
TypeFire

Posted on Fully Autonomous

Markdown Live Preview: 4 Ways to See What Your README Really Looks Like Before You Push

#markdown #github #webdev #productivity

You write a README, push it, open the repo page, and the table is a mess of pipes. The list you indented "correctly" is now a code block. The checkbox is a literal [ ].

Markdown is forgiving to write and unforgiving to render. A live preview catches all of that before anyone else sees it. Here are four ways to get one, depending on where you're writing, plus the mistakes worth looking for.

1. VS Code: the preview you already have

VS Code ships a Markdown preview, no extension needed.

  • Cmd+Shift+V (Mac) or Ctrl+Shift+V (Windows, Linux) opens the preview in a tab.
  • Cmd+K V or Ctrl+K V opens it side by side, and it scrolls along with the editor.

Good for: files that already live in a repo you have open.

2. GitHub's own Preview tab

Editing a .md file in the GitHub web editor? The Preview tab next to Edit renders it with GitHub's own flavor of Markdown, the same one your repo page uses.

Good for: quick fixes to a file that's already on GitHub.

3. grip: GitHub rendering on localhost 

pip install grip
grip README.md
# then open http://localhost:6419
Enter fullscreen mode Exit fullscreen mode

grip renders the file through GitHub's Markdown API, so what you see matches the repo page closely. It refreshes when you save.

Good for: checking a README exactly the way GitHub will show it, from the terminal.

4. A browser editor where the preview is the document

Sometimes there's no repo yet. Someone pasted Markdown into Slack, an AI tool answered with a page of ## and **, or you're on a machine where you can't install anything.

For that, we built a free Markdown live preview at TypeFire. You paste Markdown in and it renders the moment it lands, right where you pasted it. There's no second pane to keep in sync, because the rendered text is the thing you edit.

A README pasted into the TypeFire Markdown live preview, rendered in place
A README pasted in: the heading, inline code and the table render where you pasted them.

A few details that matter for developer work:

  • Paste a README or drop the .md file onto the page; tables, fenced code, task lists and links render as they land.
  • Pasting from a web page or a doc converts to Markdown with the headings, links and lists kept, which is handy when you're turning a Google Doc into a README.
  • Copy it back out either way: File > Copy > As Markdown for the source, or As rich text for an email or a chat.
  • Nothing is uploaded. Your text stays in the browser tab, and tabs are saved locally so a refresh doesn't lose them.

Rich text from a web page pasted in and converted to Markdown
Pasted from a web page: the heading, bold, link and list arrive as Markdown.

The File menu with Copy as Markdown and Copy as rich text
File > Copy gives you the source or the formatted version.

The same editor also ships in TypeFire for Chrome, with your notes in tabs, a text expander and clipboard history:

Good for: Markdown that doesn't live in a repo yet, or anywhere you can't install tools. If you just need to read a .md file on a Mac rather than edit it, the Markdown viewer for Mac guide covers that.

What to look for in the preview

Whichever tool you use, these are the five mistakes a preview catches that your eyes skip in raw Markdown:

1. Tables without a separator row. The second line has to be dashes and pipes, or there's no table:

| Flag | What it does |
| --- | --- |
| `-v` | Verbose output |
Enter fullscreen mode Exit fullscreen mode

Here's the same table without that row, and then with it:

A Markdown table missing its separator row, shown as raw pipes
No separator row: just text with pipes in it.

The same table with the separator row, rendered as a table
Add | --- | --- | and it becomes a table.

2. A numbered list that doesn't start at 1. On GitHub a bullet list can follow a paragraph directly, but a numbered list starting at 3. with no blank line above it merges into the paragraph. Add the blank line, or start at 1..

3. Nested lists indented by the wrong amount. Line nested items up under the text of the parent item. Too little indent and the child item flattens into the parent list.

4. Task lists that need the exact syntax. It's - [ ] and - [x], with a space inside the empty brackets and a space after them. -[ ] stays as literal text.

5. Fenced code without a language.

```bash

gets syntax highlighting; a bare

```

doesn't. The preview shows you which blocks you forgot to tag.

Which one should you use?

  • Writing inside a repo in VS Code: the built-in preview.
  • Fixing a file on GitHub: the Preview tab.
  • Want GitHub's exact rendering locally: grip.
  • Markdown from anywhere else, or no install allowed: a browser live preview.

What's the Markdown rendering bug that bit you last?

Top comments (0)