Markdown is a family of renderers
CommonMark defines a stable core for paragraphs, headings, emphasis, links, lists, block quotes, and code. GitHub Flavored Markdown adds tables, task lists, strikethrough, and autolinks. Footnotes, alerts, emoji, syntax highlighting, and math depend on extensions.
The same source can render differently across GitHub, documentation systems, static generators, note apps, and email tools. Portability begins by identifying the target renderer.
Build a durable structure
- Use one H1 only when the destination expects it in the source.
- Keep H2 and H3 order logical.
- Write paragraphs without unnecessary manual line breaks.
- Use fenced code blocks with a language label.
- Keep links and image paths stable.
- Make the source readable even when extensions disappear.
Tables are useful but limited
| Need | Markdown table | Alternative |
|---|---|---|
| Compact comparison | Good | None |
| Long prose in cells | Hard to maintain | Headings or definition list |
| Row/column spans | Not portable | HTML where allowed |
| Machine-readable data | Weak | CSV/JSON plus rendered view |
Task lists are notation, not a project database
Task-list syntax is useful for checklists, release readiness, and issue templates. It does not provide ownership, due dates, dependencies, reminders, or audit history. Move operational work to a task system when accountability matters.
Footnotes and alerts depend on extensions
Footnotes keep side explanations out of the main sentence, but they are not core CommonMark. GitHub alerts add visual note, warning, and caution blocks; other renderers may show them as ordinary quotes. Write the words so they remain clear without the styling.
Enhancement may disappear. Meaning must survive.
Code and math
Use fenced code blocks with a language hint. The label controls highlighting; it does not execute code. Do not paste secrets into any editor whose data path is not approved.
Math syntax depends on a renderer such as KaTeX. Unsupported LaTeX packages and commands will not work automatically. Provide plain-language explanation around important formulas and verify accessibility in the final output.
Use Jivaro’s Markdown Editor
- Open Markdown Editor & Previewer.
- Start blank, import a file, or use an example.
- Inspect the live preview while writing.
- Test tables, tasks, footnotes, alerts, code, emoji, and math separately.
- Use autosave as convenience, not the only backup.
- Export Markdown as the editable master.
- Export HTML when rendered output is required.
- Open the exported HTML separately and inspect links, headings, code, tables, and math.
HTML export needs a trust boundary
If user-controlled Markdown can contain raw HTML, sanitize the output before publishing. Also check whether export includes styling or only semantic HTML; pasted output may look different under another site’s CSS.
Portability checklist
Headings, links, lists, and code remain understandable.
State whether GFM, footnotes, alerts, emoji, or math are required.
Keep linked assets predictable.
Validate output and untrusted input.
Rendered HTML should not become the only editable copy.
The destination is authoritative.
Design a compatibility profile
For recurring documentation, write down the renderer and extensions you support. A GitHub profile might allow GFM tables and tasks but avoid raw HTML. A technical site may add footnotes, syntax highlighting, alerts, and KaTeX. A cross-platform profile may limit content to CommonMark plus ordinary links and fenced code.
Run the same fixture document through each supported renderer after upgrades. The fixture should contain nested lists, code fences, a table, links, images, Unicode, footnotes, alerts, and math. Differences become visible before they affect published documentation.
Version images and linked files with the source
Broken images and downloads often come from moving Markdown without its assets. Use predictable relative paths, descriptive filenames, intrinsic dimensions in generated HTML, and a link checker. When a document is exported or copied to another platform, verify that every local asset was transferred or replaced with an absolute canonical URL.
Frequently asked questions
No. They are commonly supplied by extensions such as GitHub Flavored Markdown.
No. Other renderers may display them as ordinary block quotes or unsupported syntax.
No. Raw HTML and generated HTML should be sanitized according to the destination’s trust model.
It remains simpler to edit, version, and move to another renderer.
Related Jivaro apps
Write, search, preview, import, autosave, and export Markdown with CodeMirror, synchronized scrolling, Mermaid diagrams, frontmatter, tables, syntax highlighting, and math.
Open appSources and references
- CommonMark SpecificationCommonMark · reference
- GitHub Flavored Markdown SpecificationGitHub · reference
- GitHub writing and formatting syntaxGitHub Docs · reference
- KaTeX Supported FunctionsKaTeX · reference
- Markdown Editor & PreviewerJivaro · first-party