Introduction
CommonMark is the standardized core of Markdown — headings, lists, links, emphasis, code spans. GFM (GitHub Flavored Markdown) adds tables, task lists, strikethrough, and auto-linking. Extended Flavors add footnotes, definition lists, math (LaTeX), and custom containers. When writing open-source documentation, stick to GFM — it is the most widely supported. Use extended features only when you control the renderer (like a static site generator).
CommonMark vs GFM vs Extended Flavors
CommonMark is the standardized core of Markdown — headings, lists, links, emphasis, code spans. GFM (GitHub Flavored Markdown) adds tables, task lists, strikethrough, and auto-linking. Extended Flavors add footnotes, definition lists, math (LaTeX), and custom containers. When writing open-source documentation, stick to GFM — it is the most widely supported. Use extended features only when you control the renderer (like a static site generator).
Advanced Markdown Techniques
Reference-style links ([text][ref] with [ref]: url at the bottom) keep the source readable and make translation easier. Fenced code blocks with a language tag enable syntax highlighting. Collapsible sections using are widely supported. For tables, use colon placement for alignment: left-aligned (:---), centered (:---:), right-aligned (---:). Always include a blank line before headings and lists for correct block-level parsing.
Validation with Our Markdown Editor
Our Markdown Editor provides live preview, character/word count, and syntax validation. Paste your draft, toggle between source and preview, and verify the output matches your expectations before committing to your documentation repository.
Frequently Asked Questions
What is the difference between CommonMark and GitHub Flavored Markdown?
CommonMark is the standardized core specification for Markdown covering headings, lists, links, emphasis, and code blocks. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and auto-linking of URLs and email addresses. For open-source documentation, stick to GFM for maximum compatibility. Use extended features only when you control the rendering platform.
How do I create tables in Markdown?
Use pipes (|) to separate columns and hyphens (-) to create the header row separator. Align columns using colons: --- for left-aligned, :---: for centered, and ---: for right-aligned. Always include a blank line before and after the table for proper parsing. Example: | Header 1 | Header 2 | followed by | --- | --- | and then your data rows.
Why do my Markdown links not render correctly?
Common causes include missing spaces between the link text and URL, using wrong bracket types, or forgetting the parentheses around the URL. The correct format is [link text](https://example.com). For reference-style links, ensure the reference label matches exactly (case-sensitive) and the URL definition is on its own line. Always test links before publishing documentation.
How do I add syntax highlighting to code blocks?
Use fenced code blocks with a language identifier after the opening backticks: ```javascript for JavaScript, ```python for Python, ```bash for shell commands. The language tag tells the renderer which syntax highlighting rules to apply. Most documentation platforms support hundreds of languages. Use the language identifier even for plain text (```text) to maintain consistent formatting.
Can I use HTML directly in Markdown?
Most Markdown renderers allow inline HTML, but it reduces portability. CommonMark allows raw HTML blocks and inline elements. GFM sanitizes certain tags (like script and style) for security. If your Markdown will be rendered in multiple platforms, minimize HTML usage. When HTML is necessary, use it for elements Markdown cannot express, like details/summary collapsible sections.
How do I write mathematical expressions in Markdown?
Standard Markdown does not support LaTeX math, but extended flavors do. Use $...$ for inline math and $$...$$ for block math. Platforms like Jekyll (with MathJax), GitBook, and Obsidian support this syntax. The math content renders as formatted equations using MathJax or KaTeX. Use the \() and \[] delimiters for broader compatibility across renderers.
What is the best Markdown editor for technical documentation?
The best editor depends on your workflow. VS Code with the Markdown All in One extension offers live preview, auto-formatting, and Git integration. Typora provides a seamless WYSIWYG experience. Online editors like our Markdown Editor are ideal for quick validation and sharing. For team documentation, consider platforms like Notion, Confluence, or GitBook that combine Markdown with collaboration features.
How do I handle long documentation files in Markdown?
Break large files into sections using a table of contents at the top with anchor links. Use reference-style links to keep the main text readable. Consider splitting into multiple files for very long documentation and using a documentation generator like MkDocs, Docusaurus, or GitBook to combine them. Keep each file focused on a single topic for better maintainability.
Conclusion
Mastering Markdown for technical documentation means understanding the differences between CommonMark, GFM, and extended flavors, then choosing the right feature set for your audience. By using reference-style links, fenced code blocks with language tags, and proper heading hierarchy, you create documentation that is portable, readable, and easy to maintain across platforms. Validate your output before publishing to ensure consistent rendering everywhere.
Frequently asked questions
What is the difference between CommonMark and GitHub Flavored Markdown?
CommonMark is the standardized core specification for Markdown covering headings, lists, links, emphasis, and code blocks. GitHub Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, and auto-linking of URLs and email addresses. For open-source documentation, stick to GFM for maximum compatibility. Use extended features only when you control the rendering platform.
How do I create tables in Markdown?
Use pipes (|) to separate columns and hyphens (-) to create the header row separator. Align columns using colons: --- for left-aligned, :---: for centered, and ---: for right-aligned. Always include a blank line before and after the table for proper parsing. Example: | Header 1 | Header 2 | followed by | --- | --- | and then your data rows.
Why do my Markdown links not render correctly?
Common causes include missing spaces between the link text and URL, using wrong bracket types, or forgetting the parentheses around the URL. The correct format is [link text](https://example.com). For reference-style links, ensure the reference label matches exactly (case-sensitive) and the URL definition is on its own line. Always test links before publishing documentation.
How do I add syntax highlighting to code blocks?
Use fenced code blocks with a language identifier after the opening backticks: ```javascript for JavaScript, ```python for Python, ```bash for shell commands. The language tag tells the renderer which syntax highlighting rules to apply. Most documentation platforms support hundreds of languages. Use the language identifier even for plain text ( ```text ) to maintain consistent formatting.
Can I use HTML directly in Markdown?
Most Markdown renderers allow inline HTML, but it reduces portability. CommonMark allows raw HTML blocks and inline elements. GFM sanitizes certain tags (like script and style) for security. If your Markdown will be rendered in multiple platforms, minimize HTML usage. When HTML is necessary, use it for elements Markdown cannot express, like details/summary collapsible sections.
How do I write mathematical expressions in Markdown?
Standard Markdown does not support LaTeX math, but extended flavors do. Use $...$ for inline math and $$...$$ for block math. Platforms like Jekyll (with MathJax), GitBook, and Obsidian support this syntax. The math content renders as formatted equations using MathJax or KaTeX. Use the \() and \[] delimiters for broader compatibility across renderers.
What is the best Markdown editor for technical documentation?
The best editor depends on your workflow. VS Code with the Markdown All in One extension offers live preview, auto-formatting, and Git integration. Typora provides a seamless WYSIWYG experience. Online editors like our Markdown Editor are ideal for quick validation and sharing. For team documentation, consider platforms like Notion, Confluence, or GitBook that combine Markdown with collaboration features.
How do I handle long documentation files in Markdown?
Break large files into sections using a table of contents at the top with anchor links. Use reference-style links to keep the main text readable. Consider splitting into multiple files for very long documentation and using a documentation generator like MkDocs, Docusaurus, or GitBook to combine them. Keep each file focused on a single topic for better maintainability.