Markdown is the standard format for documentation, READMEs, and simple website content. But without a preview, it is easy to mis-format lists, tables, and code blocks. This guide explains how Markdown rendering works and why the ToolOrbit Markdown Previewer is useful for writing with confidence.
Markdown basics
- Use # headings, - or * lists, and fenced code blocks for readability.
- Links are written as [text](url).
- Tables are created with pipes and dashes.
- Task lists support - [ ] and - [x] in GitHub-flavoured Markdown.
Common formatting pitfalls
- Missing blank lines before or after lists.
- Fenced code blocks without the closing triple backticks.
- Incorrect table column alignment or missing pipe separators.
- Inline HTML that breaks Markdown parsing in some renderers.
Preview and HTML output
ToolOrbit renders your Markdown live while also generating the equivalent HTML. That makes it easy to check whether the formatted result matches your intent, and to copy the HTML into a web page or CMS if needed.
Markdown beyond the first paragraph
- Nested lists: indent child items four spaces to nest them correctly.
- Task lists: - [ ] and - [x] render as checkboxes in GitHub-flavoured Markdown.
- Footnotes and definition lists are extension features — they only work in specific renderers.
- Autolinks: paste a full URL and most renderers will turn it into a link for you.
Why a live preview earns its place
Markdown’s whole point is readable source, but headers, lists and tables still have enough edge cases that “it looked fine” is a common preparation for a broken publish. A preview that renders as you type catches the missing blank line, the unterminated code fence and the misaligned table before the document reaches a README, a CMS or a docs site — where the reader will not care that the source was convenient.
GitHub-flavoured extras that change the output
Tables, strikethrough, task lists and autolinks are GitHub-flavoured Markdown (GFM) extensions, not core Markdown — they render in GitHub, Slack and most repo tools, but fail in strict parsers. Fit your preview to your final destination: previewing with GFM while publishing to a strict parser silently drops half your formatting. Similarly, HTML inside Markdown works in GFM but may be sanitised elsewhere, so treat inline HTML as a portability risk rather than a feature.
- fence code blocks with the language tag — syntax highlighting depends on it.
- Blank lines around headings and lists are not optional; they structure the block.
- Keep link destinations on one line — wrapping breaks reference links.
