Tables and task lists are powerful, but portability depends on renderer support.
Extension overview
GitHub Flavored Markdown adds several extensions to the CommonMark base. The most important are tables, task list items, strikethrough, and extended autolinks. Each extension solves a practical authoring problem, but each also introduces compatibility considerations. A document that uses these features is no longer strictly CommonMark-only.
Understanding GFM extensions requires looking at both syntax and semantics. Syntax defines what source text is recognized. Semantics define what the recognized structure means in output. A task list item, for example, is syntactically a list item with a checkbox marker. Semantically, it may become an HTML checkbox, and on GitHub it can integrate with issue state or interaction behavior.
Tables
GFM tables use pipes and a delimiter row. They are popular in README files because they make comparisons easy: options, parameters, compatibility matrices, pricing tiers, and command summaries. A basic table has a header row, a separator row, and body rows.
Tables are useful, but they have limitations. Complex tables are hard to read in source. Cell content support is limited compared to HTML tables. Pipes inside content may need escaping. Alignment markers can define left, right, or center alignment, but rendering depends on CSS.
For technical documentation, use tables for compact comparisons, not for long explanations. If a table cell contains multiple sentences, a section with headings may be better. Tables should enhance scannability, not hide important prose from readers.
Task list items
Task lists extend list items with checkbox markers such as [ ] and [x]. They are especially useful for issue templates, release checklists, migration steps, and project planning. In rendered HTML, they often become disabled or interactive checkboxes depending on platform behavior.
Task list items are semantically different from ordinary lists because they express state. An unchecked item is not just a bullet; it communicates incomplete work. This makes them valuable in collaborative contexts. It also means exporting task lists to systems without support can lose meaning.
If your product supports task lists, decide whether users can toggle them in rendered views or only edit source. Also decide how state is stored. In pure Markdown, state is stored as text. In a platform integration, state may also update external issue metadata. Mixing those models requires care.
Strikethrough
GFM strikethrough uses tildes to mark deleted or obsolete text. It is common in discussions, changelogs, and documents that preserve edits. Strikethrough can communicate “this used to be true, but no longer is.”
Use strikethrough sparingly in durable documentation. In a final tutorial or reference page, it is usually better to replace obsolete text or explain version differences clearly. Strikethrough is more appropriate in collaborative conversation, notes, or migration guides where showing change history is useful.
From a parser perspective, strikethrough adds another inline delimiter type. It interacts with surrounding text and other inline constructs. GFM defines the behavior so tools can implement it consistently.
Autolinks
GFM extends autolink behavior so URLs can become links even without angle brackets. This is convenient in comments and issues where users paste links casually. GFM also supports special linking behavior in GitHub contexts, such as references to issues, pull requests, commits, and users, though platform-specific references are beyond generic Markdown syntax.
Automatic linking improves convenience but can surprise authors when trailing punctuation is captured incorrectly or when text that was intended to remain plain becomes a link. In formal documentation, explicit links are often better because they provide descriptive anchor text and predictable boundaries.
Disallowed raw HTML
GFM includes rules around disallowed raw HTML tags. This is connected to GitHub’s security posture. User-generated content cannot be allowed to execute arbitrary scripts or inject unsafe markup. The extension model therefore includes not only new authoring features but also restrictions.
This is a reminder that a Markdown dialect is not only additive. It may also constrain behavior to protect users. If your application supports GFM, study both the added syntax and the safety model.
Portability guidance
Use GFM extensions when your target environment supports them. For GitHub README files, tables and task lists are normal. For portable Markdown archives, use them cautiously. For documents that may be converted through Pandoc, static site generators, or custom renderers, test output in the full pipeline.
When portability matters, provide fallback context in prose. Do not put critical meaning only in a task checkbox or table layout. A paragraph explaining the state or comparison can survive more conversions than a dialect-specific feature.
Extension review checklist
Before enabling a GFM extension, define its source syntax, rendered output, accessibility behavior, export behavior, and fallback behavior. Tables should remain readable in source. Task lists should expose state clearly. Autolinks should not create misleading anchors. Raw HTML restrictions should be documented.
This checklist keeps extensions from becoming accidental product commitments. Once users rely on an extension, removing or changing it becomes a migration event.
Accessibility should be part of the same review. Tables need meaningful headers. Task list checkboxes need understandable labels. Strikethrough should not be the only signal that text is obsolete. Autolinks should have surrounding context so users know where they lead.
FAQ
Are GFM tables part of CommonMark?
No. Tables are a GFM extension, not part of CommonMark core.
What is a task list item?
A task list item is a list item with checkbox syntax, usually [ ] for incomplete and [x] for complete.
Is strikethrough portable Markdown?
Not universally. It is supported in GFM and many tools, but not in strict CommonMark.
Are bare URLs always autolinked in Markdown?
Bare URL autolinking is a GFM extension. CommonMark supports angle-bracket autolinks.
Should documentation rely on GFM extensions?
Only if the target renderer supports GFM. For portability, document the dependency and provide prose context.
Related tutorials
- Understand the GFM base in GitHub Flavored Markdown.
- Compare extension portability in Markdown Dialects Compared.
- Link GFM autolinks to Markdown Links, Images, and Reference Definitions.
- Model extension output in Markdown AST with mdast.
- Enforce extension policy in Designing Production Markdown Systems.
Continue with Markdown AST with mdast.