Practical Markdown workflow
How to Check Markdown Preview Before You Export
By KenRich ยท Last updated: September 10, 2026
A Markdown file can look fine in the source and still go wrong in a preview, HTML page, or PDF. This checklist gives you a short way to find those problems before you share the document.
Read the structure before you polish the wording
Start with the headings. A title should describe the document, and the sections below it should follow a path that makes sense to someone who did not write the first draft.
Then read the preview from top to bottom. Look for a heading that appears too early, a paragraph that belongs under another section, or a list that should be ordinary prose. These problems are easier to fix before you spend time on fonts and page layout.
A useful first pass only asks whether the document is easy to follow. Do not try to solve every visual detail at once.
# Release checklist
## Before editing
Check the source and decide what the reader needs to know.
## Before export
- Review the structure
- Check the examples
- Open the exported file
## Next step
Share the source beside the final output.Release checklist
Before editing
Check the source and decide what the reader needs to know.
Before export
- Review the structure
- Check the examples
- Open the exported file
Next step
Share the source beside the final output.
NoteThe headings show the order of the work before the details become longer.
Check lists and tables at their widest point
Numbered lists can lose their numbering when separate lists are joined during export. Read the numbers in the preview instead of assuming the source will produce the result you expect.
Tables need a different check. Look at the widest row, the longest heading, and the last column. A table that fits a wide editor may wrap badly in a PDF with fixed page margins.
If a table needs several sentences in each cell, it may be carrying too much information. Move the explanation into a paragraph and keep the table for short comparisons.
## Output check
1. Open the source file.
2. Read the rendered document.
3. Review the exported copy.
| Output | What to inspect |
| --- | --- |
| HTML | Links, images, and code spacing |
| PDF | Page breaks, tables, and page numbers |
| Markdown | Source remains readable and complete |Output check
- Open the source file.
- Read the rendered document.
- Review the exported copy.
| Output | What to inspect |
|---|---|
| HTML | Links, images, and code spacing |
| Page breaks, tables, and page numbers | |
| Markdown | Source remains readable and complete |
NoteUse short cells so the table remains useful in both the preview and the exported file.
Check code and math as rendered content
A code block should show the language it uses when syntax highlighting helps the reader. Check that the block keeps its spacing and that long lines do not hide the important part of the example.
For formulas, check the delimiters as well as the result. Inline math belongs inside a sentence. A larger equation should have its own block and a short explanation nearby.
Do not judge a formula only by the source. A missing delimiter can leave raw characters in the preview or make the expression look like ordinary text.
Run the test before exporting:
```bash
npm test
```
The average is written as $\bar{x}$, while the full expression gets its own block:
$$\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$$Run the test before exporting:
npm test
The average is written as $\bar{x}$, while the full expression gets its own block:
$$\bar{x} = \frac{1}{n}\sum_{i=1}^{n}x_i$$
NoteThe preview should show a highlighted command and a formatted equation, not their raw delimiters.
Open every important image and link
A broken image often comes from a path that only works on the author's machine. Check images after moving the Markdown file, especially when the path points to a nearby assets folder.
Open important links from the rendered preview. The link text should tell readers where they are going, and an image should have alt text that still makes sense if the image does not load.
For a document that will be shared, check one link in the HTML output as well. The destination may be correct in the Markdown source but changed by a publishing step.
Read the [Markdown basics guide](/docs/markdown-basics) before sharing the draft.
Read the Markdown basics guide before sharing the draft.
NoteUse a real image while reviewing the preview, then keep local images beside the Markdown file when the document needs to travel.
Review HTML and PDF for different problems
HTML is usually the better choice when the next step is a website, help center, or documentation system. Check links, images, code spacing, and the reading width.
PDF is a fixed page format. Check the first page, a page with a heading near the bottom, the widest table, code blocks, page numbers, and any Chinese or mixed-language text. A PDF can look correct on one page and fail at a section boundary.
Use the same source for both outputs, then keep the output that matches the next job. Do not keep editing the exported file as if it were the source document.
## Before sharing
- [ ] Read the preview from start to finish
- [ ] Check the widest table
- [ ] Open important links and images
- [ ] Check code, math, and Mermaid diagrams
- [ ] Open the HTML or PDF after export
- [ ] Keep the Markdown source beside the outputBefore sharing
- [ ] Read the preview from start to finish
- [ ] Check the widest table
- [ ] Open important links and images
- [ ] Check code, math, and Mermaid diagrams
- [ ] Open the HTML or PDF after export
- [ ] Keep the Markdown source beside the output
NoteThe checklist is short enough to use for every document that matters.
Keep the Markdown source with the result
The exported file is a delivery copy. The Markdown file is the version you can search, compare, reopen, and revise. Keep both when the document may change again.
VeloWrite keeps the source and rendered result close together while you work. In the web editor, download the Markdown copy before closing a temporary draft. In the desktop app, save the file in a folder you already back up.
This habit also makes feedback easier. When someone reports a layout problem, you can return to the exact source, reproduce the preview, and compare the next export with the previous one.