How to Preview Markdown Before You Publish It

October 17, 2026 • NOFYI Editorial Team

Markdown looks simple on the surface. You type a few symbols, and a heading, a link, or a list appears. That simplicity is also the reason previewing matters. A small mark in the wrong place can change a heading into plain text, break a link, or turn a whole paragraph into a code block. Previewing before you publish is the habit that catches those mistakes while they are still easy to fix.

This guide explains how to preview Markdown in a practical way. It covers the basic method, the checks that matter most, and a worked example you can follow from start to finish. It also explains why a preview can look different on different platforms, and why you should always check on the site where the content will actually appear.

What Markdown Preview Means

Markdown is a plain-text way of writing formatted content. You write bold with two asterisks, a heading with a hash symbol, and a link with brackets followed by parentheses. A Markdown renderer then converts that plain text into HTML, which a browser displays as formatted content. Previewing shows you the result of that conversion before anyone else sees it.

A preview is not just a nice extra. It is a check on meaning. Readers do not see your source text. They see the rendered result. If a heading is not recognised, if a list does not start correctly, or if a link points to the wrong address, the reader experiences the broken version. Previewing lets you compare what you intended with what the renderer actually produced.

It also helps you spot problems that are hard to see in plain text. A missing blank line, an extra space, or an unclosed formatting mark can affect several lines at once. In the source, those problems look tiny. In the preview, they are obvious because the layout changes.

How to Preview Markdown Before You Publish It

Use the following steps as a repeatable routine. They work whether you are writing a blog post, documentation, a README file, or a page for a content management system.

Step 1: Write the Draft in Plain Markdown

Start with the structure before you worry about fine details. Write the main heading, the section headings, the paragraphs, and the lists. Keep one blank line between blocks. That blank line matters because many renderers use it to separate paragraphs, headings, lists, and code blocks. Without it, two blocks can run together.

Use consistent heading levels. A single top-level heading usually introduces the page. The next level introduces major sections, and the level after that introduces subsections. Do not skip a level for visual effect, because the structure should make sense even without styling. A clear structure also makes the preview easier to scan.

Step 2: Open a Preview That Matches the Target

Choose a preview that is as close as possible to the place where the content will be published. If the content will appear on a particular website, use that website preview when it is available. If it will appear in a repository, use the preview offered by that platform. If you are writing for a static site generator, build or preview the site locally when you can.

A generic Markdown editor is useful for a first check, but it should not be the only check. Different renderers support different extensions, handle line breaks differently, and style elements in their own way. A preview that matches the target reduces the chance of a surprise after publication.

Step 3: Compare the Preview With Your Intention

Read the preview as a reader would, not as the writer. Start at the top and move through the page in order. Check that each heading appears at the right level, that each list has the right items, and that each link is clickable and goes to the right place. Check that bold and italic text appear only where you intended them.

Pay attention to spacing. A paragraph that looks crowded in the preview may need a blank line or a shorter sentence. A list that appears as one long paragraph may need a blank line before it. Small layout problems are often easier to fix in the source once you can see them in the preview.

Step 4: Check Headings, Bold Text, and Links

Headings, bold text, and links are the three features most likely to be noticed first, so check them first. A heading needs a hash symbol, a space, and then the heading text. For example, # Heading is a heading, while #Heading without a space may not be recognised by every renderer.

Bold text needs matching markers at the start and end. If one marker is missing, the formatting can continue far beyond the intended words. Links need the text in square brackets and the address in parentheses, with no space between them. A useful way to check links is to hover over each one in the preview and confirm the destination before you publish.

For a link, the source looks like this: Example website. In Markdown, you would write the text in brackets and the address in parentheses. In the preview, you should see only the link text, styled as a link, and the address should appear when you hover over it.

Step 5: Check Lists, Code, and Images

Lists need consistent markers and a blank line before the first item in many renderers. Use a hyphen or an asterisk for unordered lists, and numbers followed by a period for ordered lists. Indent nested items clearly. If a nested item appears at the wrong level in the preview, adjust its indentation and check again.

Code needs care because a small change can alter the meaning. Inline code uses single backticks. A longer block uses three backticks on their own lines at the start and end. If the closing fence is missing, the rest of the page can appear as code. In the preview, code should be in a distinct style, and nothing after the block should be affected by it.

Images need a description, a file path or address, and a check that the image actually loads. If the image does not load in the preview, check the path, the file name, and whether the file exists in the expected location. Do not assume an image that loads on your computer will load for every reader.

Step 6: Check on the Target Site

After the general preview looks correct, check on the target site itself. Paste or import the content into the publishing system and use its preview or draft view. Look at the page on a desktop screen and, when possible, on a smaller screen as well. Tables, long links, and wide code lines can behave differently at different widths.

This step is important because the target site may apply its own styles, strip some HTML, or support a different set of Markdown extensions. A footnote, a table, a highlighted block, or a custom component may work in one system and not in another. The target-site preview is the closest evidence you have before publication.

Step 7: Fix, Preview Again, Then Publish

Fix any problems in the source, not in the preview. The preview is a reflection of the source, so editing the preview directly will not last. After each round of fixes, preview again. It is common for one fix to reveal another issue, especially when formatting markers are involved.

When the preview matches your intention, do a final read for spelling, grammar, and accuracy. Then publish. If the platform offers a scheduled or draft option, that option can give you one more chance to review the live page before it is widely seen.

Worked Example

Suppose you want to publish a short guide about checking a link. You start with the following Markdown source:

# How to Check a Link

Open the page and look for the **link text**. Click it and confirm that it opens the page you expect.

Useful checks:

- The link text describes the destination.
- The address is correct.
- The page loads without an error.

Learn more on the [Example website](https://example.com).

In a correct preview, you should see a top-level heading, a paragraph with the words link text in bold, a three-item bulleted list, and a final paragraph with a clickable link. The link text should read Example website, and the address should be the example address.

Now suppose the source is missing a blank line before the list. The list may not render as a list in some renderers. Instead, the list items may appear as part of the paragraph. The preview makes that problem visible. You add the blank line, preview again, and the list appears correctly.

Suppose instead that one asterisk is missing from the bold text. The preview may show an asterisk as a literal character, or bold formatting may extend further than intended. The fix is to restore the matching markers and preview again. In both cases, the worked example shows the same principle: compare the source with the preview, and trust the preview as the version readers will see.

Why a Preview Can Differ by Platform

Markdown is not a single fixed standard. The original description of Markdown left some details open, and later systems added their own extensions. CommonMark and GitHub Flavoured Markdown are widely used, but they are not identical to every other renderer. As a result, the same source can produce different output in different places.

Tables are a common difference. Some renderers support tables, and some do not. Footnotes, strikethrough, task lists, and syntax highlighting are also extensions rather than universal features. If you rely on one of these features, check that the target platform supports it.

Line breaks are another difference. Some renderers treat a single line break in the source as a new line in the output. Others treat it as a space and require a blank line for a new paragraph. If your preview shows paragraphs running together, check the line-break rules of the target renderer.

Styling is also different. Two platforms can render the same heading, list, or blockquote with different fonts, spacing, and colours. That is normal. The goal of previewing is not to make every platform look identical. It is to confirm that the structure, the links, and the meaning are correct on the platform that matters.

Limitations

Previewing is a useful check, but it has limits. A preview cannot confirm that a link destination is accurate, honest, or safe. It can show that a link is clickable, but you still need to visit the destination and confirm that it is the page you intend to recommend. A preview also cannot confirm that facts, dates, or instructions are correct.

A preview may not show how the page will look in every browser, device, or assistive technology. It may not reveal how a page behaves when styles fail to load, when images are blocked, or when a reader uses a screen reader. A preview is one check, not a complete quality review.

A preview can also hide problems in the source that only appear later. For example, a renderer may accept a feature that another system later removes during import. That is why checking on the target site matters. Even then, a live page can change after publication if a theme, plugin, or platform update changes how content is rendered.

Finally, previewing does not replace editing. A page can render perfectly and still be unclear, too long, or poorly organised. Read the content for clarity as well as for formatting.

Frequently Asked Questions

Do I need a special tool to preview Markdown?

No. Many editors, repositories, documentation systems, and content platforms include a preview. Use the preview that is closest to the publishing target. A general-purpose Markdown editor is useful for drafting, but the target-site preview is the more reliable final check.

Why does my heading not appear as a heading?

The most common cause is a missing space after the hash symbol. Another cause is a missing blank line before the heading, or a heading written inside a code block. Check the source, add the space and blank line, and preview again.

Why does my list appear as plain text?

A list may need a blank line before it, consistent markers, and correct indentation. A list inside a paragraph, or a list with mixed markers and irregular spacing, may not be recognised. Fix the spacing and indentation, then preview again.

Should I trust one preview for every platform?

No. Do not trust one preview for every platform. Different renderers support different extensions and line-break rules. Always check on the site or system where the content will be published, and treat that preview as the final check.

Conclusion

Previewing Markdown before you publish is a short habit with a clear benefit. It lets you check headings, bold text, links, lists, code, and images before readers see them. It also helps you notice when a platform renders content differently from another preview. Write the draft, preview it on the target site, fix the source, and preview again. That routine will not make every page perfect, but it will prevent many of the most common and most visible mistakes.