GitHub Flavored Markdown Guide: Tables, Task Lists, More
GitHub Flavored Markdown (GFM) is the Markdown dialect used across GitHub: in READMEs, issues, pull requests, comments, wikis, and project boards. It extends the CommonMark specification with features that make collaborative software development communication clearer. If you use GitHub regularly, understanding every GFM feature saves significant time. This guide covers all GFM extensions — tables, task lists, strikethrough, autolinks, and more — with copy-ready syntax examples you can test immediately in the WikiPlus Markdown Preview tool.
GFM Tables: Syntax, Alignment, and Best Practices
Tables are one of the most frequently used GFM features and one of the most error-prone. Understanding the syntax precisely prevents the frustration of a table rendering as plain pipe-and-dash text. Minimum valid table syntax: ``` | Header 1 | Header 2 | | --- | --- | | Cell 1 | Cell 2 | ``` The rules: 1. The first row is always the header row. 2. The second row is always the separator row — it must contain only dashes (and optional colons and spaces). 3. Each subsequent row is a data row. 4. Every row must have the same number of pipe-separated cells. 5. The separator must have at least three dashes per column. Column alignment is controlled by colons in the separator row: - Left-align: `:---` or `:--` (default for left) - Right-align: `---:` or `--:` - Center: `:---:` or `:--:` - Default (left): `---` Tips for readable tables: Pad columns with spaces to align them visually in the source file. This is optional but makes the raw Markdown much more readable. Most Markdown editors can auto-format tables. Keep cell content short. Long sentences in table cells reduce readability. If a cell needs more than one sentence, consider restructuring the content as a definition list or bulleted section instead. Avoid nesting lists inside table cells. While technically possible in some parsers, GFM does not reliably support multi-line cell content. For tables with many columns, consider whether a list format with bold property names might be more readable. A six-column table on a narrow screen is unusable.
Task Lists, Strikethrough, and Mention Syntax
Task lists are one of the most practical GFM features. They appear in GitHub issues and pull requests as interactive checkboxes that can be clicked to update status. Task list syntax: ``` - [ ] Unchecked item - [x] Checked item - [ ] Another unchecked item ``` The `x` inside the brackets can be uppercase or lowercase. There must be a space between the brackets for unchecked items — `- []` without the space does not render as a task list. Task lists in README files render as visual checkboxes but are not interactive (clicking them does nothing). Task lists in issues and PR descriptions are interactive and clicking them updates the checked state directly. Task lists also update the progress bar shown in GitHub project boards when an issue has task list items. A project item with 3 of 5 tasks checked shows 60% completion. Strikethrough uses double tildes: `~~struck through text~~`. This renders with a horizontal line through the text. It is useful for showing deprecated options, removed features, or crossed-off list items. Autolinks: GFM automatically turns URLs that start with http:// or https:// into clickable links without any Markdown syntax. Email addresses are also auto-linked. This behavior is context-sensitive — in code blocks, URLs are not auto-linked. Mentions and references: @username mentions notify the mentioned user. #123 references link to issue or PR number 123 in the same repository. SHA hashes (long form or at least 7 characters) link to the specific commit. These are GitHub application features layered on top of GFM, not part of the GFM spec itself.
Code Blocks with Syntax Highlighting and Diagrams
GitHub supports syntax highlighting for over 500 programming languages in fenced code blocks. The language identifier after the opening backticks determines the highlighting. Common language identifiers: - `javascript` or `js` - `typescript` or `ts` - `python` or `py` - `rust` - `go` - `java` - `bash` or `sh` or `shell` - `yaml` or `yml` - `json` - `sql` - `html` - `css` - `dockerfile` - `terraform` or `hcl` GitHub also supports Mermaid diagrams in fenced code blocks with the `mermaid` language identifier. Mermaid is a JavaScript library that converts text-based diagram definitions into SVG. Supported diagram types include flowcharts, sequence diagrams, class diagrams, entity-relationship diagrams, and Gantt charts. Example Mermaid flowchart: ```mermaid graph TD; A[Start] --> B{Decision}; B -- Yes --> C[Do this]; B -- No --> D[Do that]; ``` GitHub also supports GeoJSON and TopoJSON maps, and STL 3D models, in fenced code blocks with the appropriate language identifier — these render as interactive visualizations directly in issues and READMEs. For mathematical notation, GitHub renders LaTeX math expressions using the `math` language identifier in fenced blocks, or inline with $expression$ syntax.
Collapsible Sections, Footnotes, and Advanced GFM
Several advanced features appear frequently in well-structured GitHub documentation and issues. Collapsible sections use HTML `<details>` and `<summary>` tags, which GitHub supports in rendered Markdown: ```html <details> <summary>Click to expand</summary> This content is hidden until the user clicks the summary. Markdown works inside details blocks if separated by blank lines. </details> ``` This pattern is extremely useful in README files for hiding lengthy installation instructions, complete changelogs, or technical notes that are relevant to some readers but would otherwise dominate the page. Footnotes are supported in GitHub Markdown with the syntax `[^1]` for the inline reference and `[^1]: Footnote text` at the bottom of the document. Multiple footnotes are sequentially numbered automatically. Alerts (introduced by GitHub in 2023) are a GFM extension for styled callout boxes. The syntax uses a blockquote with a special keyword: ``` > [!NOTE] > This is a note. > [!WARNING] > This is a warning. > [!IMPORTANT] > Critical information. > [!TIP] > Helpful advice. > [!CAUTION] > Dangerous action. ``` These render with colored borders and icons on GitHub, making important information much more visible. The WikiPlus Markdown Preview tool renders the standard blockquote since this is a GitHub-specific extension beyond the GFM spec. Diff syntax highlighting: use ```diff as the language identifier to render additions and deletions in standard diff format with green and red highlighting.
Frequently Asked Questions
- Why is my GFM table not rendering on GitHub?
- The most common cause is a missing or malformed separator row — the row of dashes between the header and data rows. Every column must have at least one dash and the separator row must have the same number of cells as the header. Other causes: inconsistent column counts between rows, starting the table without a blank line above it in the middle of a document, or forgetting the pipe characters at the start and end of rows. Copy your table into the WikiPlus Markdown Preview tool to diagnose the issue quickly without committing to GitHub.
- Can I use HTML inside GitHub Markdown?
- Yes, but with limitations. GitHub sanitizes HTML for security by stripping dangerous tags and attributes. Allowed elements include div, span, details, summary, img, table, tr, td, th, br, pre, code, sup, sub, kbd, and a few others. Disallowed elements include script, style, iframe, form, input, and anything with inline event handlers. Most layout and accessibility HTML works. Script tags and custom styles do not.
- Does GFM support emoji shortcodes like :tada:?
- Yes, GitHub-flavored Markdown supports emoji shortcodes. The :tada: shortcode renders as the party popper emoji. GitHub's emoji shortcode list covers all Unicode emoji plus many GitHub-specific ones like :octocat:. Emoji shortcodes are a GitHub application-layer feature — they are not part of the GFM specification and will not render in other tools that support GFM. For maximum portability, use the actual Unicode emoji characters, which render everywhere.