[{"data":1,"prerenderedAt":76},["Reactive",2],{"blog-post-markdown-for-github-complete-workflow-guide":3},{"slug":4,"title":5,"description":6,"excerpt":7,"date":8,"category":9,"author":10,"keywords":11,"readingMinutes":12,"html":13,"headings":14,"tools":46,"related":50},"markdown-for-github-complete-workflow-guide","Markdown for GitHub: The Complete Workflow Guide","A practical reference for writing Markdown on GitHub across READMEs, Issues, PRs, Wikis, and more — including which GFM features work where.","Writing Markdown on GitHub feels simple — until you discover that task lists are interactive in Issues but static in READMEs, or that > [!NOTE] renders a beautiful callout in a README but produces…","2026-05-08","platform-guides","Matt Rathbone","github markdown, github flavored markdown, github readme markdown, gfm, github wiki markdown, github pull request markdown",7,"\u003Cp>Writing Markdown on GitHub feels simple — until you discover that task lists are interactive in Issues but static in READMEs, or that \u003Ccode>> [!NOTE]\u003C/code> renders a beautiful callout in a README but produces plain text in a Wiki. GitHub Flavored Markdown (GFM) has quirks, and knowing them saves real frustration.\u003C/p>\n\u003Cp>This is a complete reference for Markdown across GitHub's different surfaces. It covers what features are available where, along with concrete patterns for making the most of each.\u003C/p>\n\u003Ch2 id=\"table-of-contents\">Table of Contents\u003C/h2>\n\u003Cul>\n\u003Cli>\u003Ca href=\"#what-is-gfm\">What is GitHub Flavored Markdown?\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#features-by-surface\">Features by surface\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#readme-best-practices\">README best practices\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#issues-and-pull-requests\">Issues and Pull Requests\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#github-wikis\">GitHub Wikis\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#alerts\">Alerts and callouts\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#diagrams\">Diagrams with Mermaid\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#github-pages\">GitHub Pages and Jekyll\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"#quick-reference\">Quick reference tools\u003C/a>\u003C/li>\n\u003C/ul>\n\u003Ch2 id=\"what-is-gfm\">What is GitHub Flavored Markdown?\u003C/h2>\n\u003Cp>GitHub Flavored Markdown (GFM) is GitHub's extension of the \u003Ca href=\"https://commonmark.org/\">CommonMark specification\u003C/a>. It adds features that aren't part of standard Markdown:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Tables\u003C/strong> — pipe-delimited, with alignment control\u003C/li>\n\u003Cli>\u003Cstrong>Task lists\u003C/strong> — \u003Ccode>- [x] done\u003C/code>, interactive in issues\u003C/li>\n\u003Cli>\u003Cstrong>Strikethrough\u003C/strong> — \u003Ccode>~~text~~\u003C/code>\u003C/li>\n\u003Cli>\u003Cstrong>Autolinks\u003C/strong> — bare URLs become clickable\u003C/li>\n\u003Cli>\u003Cstrong>Fenced code blocks\u003C/strong> with language identifiers\u003C/li>\n\u003Cli>\u003Cstrong>@mentions\u003C/strong> and issue cross-references\u003C/li>\n\u003Cli>\u003Cstrong>Alerts\u003C/strong> (callout boxes) — added in 2023\u003C/li>\n\u003Cli>\u003Cstrong>Mermaid diagrams\u003C/strong> — rendered natively since 2022\u003C/li>\n\u003Cli>\u003Cstrong>Math expressions\u003C/strong> — using \u003Ccode>$...$\u003C/code> and \u003Ccode>$$...$$\u003C/code>\u003C/li>\n\u003Cli>\u003Cstrong>Footnotes\u003C/strong> — \u003Ccode>[^1]: reference text\u003C/code>\u003C/li>\n\u003C/ul>\n\u003Cp>GFM is supported almost everywhere on GitHub, but some features behave differently depending on where you write them.\u003C/p>\n\u003Ch2 id=\"features-by-surface\">Features by Surface\u003C/h2>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Feature\u003C/th>\n\u003Cth align=\"center\">README\u003C/th>\n\u003Cth align=\"center\">Issues / PRs\u003C/th>\n\u003Cth align=\"center\">Comments\u003C/th>\n\u003Cth align=\"center\">Wiki\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>Tables\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Task lists (rendered)\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅ interactive\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Strikethrough\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>@mentions\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Issue refs (\u003Ccode>#123\u003C/code>)\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">❌\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Alerts (\u003Ccode>> [!NOTE]\u003C/code>)\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">⚠️\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Mermaid diagrams\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">⚠️\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Math (\u003Ccode>$...$\u003C/code>)\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Footnotes\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Emoji shortcodes\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>HTML \u003Ccode><details>\u003C/code>\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">⚠️\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>Collapsible \u003Ccode><summary>\u003C/code>\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003Ctd align=\"center\">⚠️\u003C/td>\n\u003Ctd align=\"center\">✅\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Cp>⚠️ = partially supported or context-dependent\u003C/p>\n\u003Ch2 id=\"readme-best-practices\">README Best Practices\u003C/h2>\n\u003Cp>The README is the homepage of your repository. Visitors make snap judgments based on it — a well-structured README earns more stars, contributors, and trust.\u003C/p>\n\u003Ch3 id=\"the-essential-structure\">The essential structure\u003C/h3>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\"># Project Name\u003C/span>\n\nOne-sentence description of what this does and who it's for.\n\n\u003Cspan class=\"hljs-section\">## Installation\u003C/span>\n\n\u003Cspan class=\"hljs-code\">```bash\nnpm install your-package\n```\u003C/span>\n\n\u003Cspan class=\"hljs-section\">## Usage\u003C/span>\n\n\u003Cspan class=\"hljs-code\">```javascript\nconst tool = require('your-package')\ntool.doSomething()\n```\u003C/span>\n\n\u003Cspan class=\"hljs-section\">## Contributing\u003C/span>\n\nSee [\u003Cspan class=\"hljs-string\">CONTRIBUTING.md\u003C/span>](\u003Cspan class=\"hljs-link\">CONTRIBUTING.md\u003C/span>).\n\n\u003Cspan class=\"hljs-section\">## License\u003C/span>\n\nMIT\n\u003C/code>\u003C/pre>\u003Ch3 id=\"badges\">Badges\u003C/h3>\n\u003Cp>Badges communicate project health at a glance. They go between the description and the first heading:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">![\u003Cspan class=\"hljs-string\">CI\u003C/span>](\u003Cspan class=\"hljs-link\">https://github.com/owner/repo/actions/workflows/ci.yml/badge.svg\u003C/span>)\n![\u003Cspan class=\"hljs-string\">npm version\u003C/span>](\u003Cspan class=\"hljs-link\">https://img.shields.io/npm/v/your-package\u003C/span>)\n![\u003Cspan class=\"hljs-string\">License: MIT\u003C/span>](\u003Cspan class=\"hljs-link\">https://img.shields.io/badge/License-MIT-yellow.svg\u003C/span>)\n![\u003Cspan class=\"hljs-string\">Downloads\u003C/span>](\u003Cspan class=\"hljs-link\">https://img.shields.io/npm/dm/your-package\u003C/span>)\n\u003C/code>\u003C/pre>\u003Cp>\u003Ca href=\"https://shields.io\">Shields.io\u003C/a> has generators for hundreds of badge types.\u003C/p>\n\u003Ch3 id=\"table-of-contents-1\">Table of contents\u003C/h3>\n\u003Cp>GitHub doesn't auto-generate a TOC, but you can create one using anchor links. GitHub auto-generates heading anchors: spaces become hyphens, everything is lowercased, punctuation is removed.\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Table of Contents\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">Installation\u003C/span>](\u003Cspan class=\"hljs-link\">#installation\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">Usage\u003C/span>](\u003Cspan class=\"hljs-link\">#usage\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Basic usage\u003C/span>](\u003Cspan class=\"hljs-link\">#basic-usage\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [\u003Cspan class=\"hljs-string\">Advanced options\u003C/span>](\u003Cspan class=\"hljs-link\">#advanced-options\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">API Reference\u003C/span>](\u003Cspan class=\"hljs-link\">#api-reference\u003C/span>)\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [\u003Cspan class=\"hljs-string\">Contributing\u003C/span>](\u003Cspan class=\"hljs-link\">#contributing\u003C/span>)\n\u003C/code>\u003C/pre>\u003Cp>For more about anchor links, see our \u003Ca href=\"/blog/markdown-internal-links\">guide to Markdown internal links\u003C/a>.\u003C/p>\n\u003Ch3 id=\"collapsible-sections\">Collapsible sections\u003C/h3>\n\u003Cp>Use HTML \u003Ccode><details>\u003C/code> and \u003Ccode><summary>\u003C/code> for content you want collapsed by default. This is great for long changelogs, large code examples, or optional configuration:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">details\u003C/span>>\u003C/span>\u003C/span>\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">summary\u003C/span>>\u003C/span>\u003C/span>Advanced configuration options\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">summary\u003C/span>>\u003C/span>\u003C/span>\n\nPut your expanded content here. Note the blank line after \u003Cspan class=\"hljs-code\">`<summary>`\u003C/span> —\nit's required for Markdown to render inside the block.\n\n\u003Cspan class=\"hljs-code\">```json\n{\n  "option": "value"\n}\n```\u003C/span>\n\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">details\u003C/span>>\u003C/span>\u003C/span>\n\u003C/code>\u003C/pre>\u003Ch3 id=\"centering-images\">Centering images\u003C/h3>\n\u003Cp>GFM doesn't support CSS classes, but you can center images with an HTML wrapper:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">p\u003C/span> \u003Cspan class=\"hljs-attr\">align\u003C/span>=\u003Cspan class=\"hljs-string\">"center"\u003C/span>>\u003C/span>\u003C/span>\n  \u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"><\u003Cspan class=\"hljs-name\">img\u003C/span> \u003Cspan class=\"hljs-attr\">src\u003C/span>=\u003Cspan class=\"hljs-string\">"./docs/logo.png"\u003C/span> \u003Cspan class=\"hljs-attr\">width\u003C/span>=\u003Cspan class=\"hljs-string\">"200"\u003C/span> \u003Cspan class=\"hljs-attr\">alt\u003C/span>=\u003Cspan class=\"hljs-string\">"Project logo"\u003C/span>>\u003C/span>\u003C/span>\n\u003Cspan class=\"language-xml\">\u003Cspan class=\"hljs-tag\"></\u003Cspan class=\"hljs-name\">p\u003C/span>>\u003C/span>\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>For more image options, see our \u003Ca href=\"/blog/markdown-image-alignment-positioning-complete-guide\">Markdown image alignment guide\u003C/a>.\u003C/p>\n\u003Ch2 id=\"issues-and-pull-requests\">Issues and Pull Requests\u003C/h2>\n\u003Cp>Issues and PRs share the same Markdown renderer as READMEs, but they add some interactive features.\u003C/p>\n\u003Ch3 id=\"interactive-task-lists\">Interactive task lists\u003C/h3>\n\u003Cp>Task lists in Issues and PRs are \u003Cem>interactive\u003C/em> — users can check boxes directly without editing the source:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Release checklist\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [x] Write unit tests\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [x] Update changelog\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [ ] Update documentation\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [ ] Tag the release\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [ ] Publish to npm\n\u003C/code>\u003C/pre>\u003Cp>GitHub shows completion status in the issue list (e.g., \u003Cem>3 of 5 tasks\u003C/em>). For more, see our \u003Ca href=\"/blog/markdown-task-lists-and-checkboxes-complete-guide\">Markdown task lists guide\u003C/a>.\u003C/p>\n\u003Ch3 id=\"cross-references-and-autolinks\">Cross-references and autolinks\u003C/h3>\n\u003Cp>GitHub auto-links many types of references in issues and PRs:\u003C/p>\n\u003Cdiv class=\"table-responsive\">\u003Ctable class=\"table\">\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Reference\u003C/th>\n\u003Cth>Links to\u003C/th>\n\u003C/tr>\n\u003C/thead>\n\u003Ctbody>\u003Ctr>\n\u003Ctd>\u003Ccode>#123\u003C/code>\u003C/td>\n\u003Ctd>Issue or PR in the same repo\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>owner/repo#123\u003C/code>\u003C/td>\n\u003Ctd>Issue or PR in another repo\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>@username\u003C/code>\u003C/td>\n\u003Ctd>GitHub user profile\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>@org/team\u003C/code>\u003C/td>\n\u003Ctd>GitHub team\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>abc1234\u003C/code> (7+ char SHA)\u003C/td>\n\u003Ctd>Specific commit\u003C/td>\n\u003C/tr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gh-123\u003C/code>\u003C/td>\n\u003Ctd>Shorthand for issue/PR\u003C/td>\n\u003C/tr>\n\u003C/tbody>\u003C/table>\u003C/div>\n\u003Cp>\u003Cstrong>Close keywords:\u003C/strong> Using \u003Ccode>closes #123\u003C/code>, \u003Ccode>fixes #123\u003C/code>, or \u003Ccode>resolves #123\u003C/code> in a PR description automatically closes the referenced issue when the PR is merged into the default branch.\u003C/p>\n\u003Ch3 id=\"issue-and-pr-templates\">Issue and PR templates\u003C/h3>\n\u003Cp>Templates live in \u003Ccode>.github/ISSUE_TEMPLATE/\u003C/code> (for issues) or \u003Ccode>.github/pull_request_template.md\u003C/code> (for PRs). They're standard Markdown files with optional YAML frontmatter:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">---\nname: Bug report\nabout: Report something that isn't working\nlabels: bug\n\u003Cspan class=\"hljs-section\">assignees: ''\n---\u003C/span>\n\n\u003Cspan class=\"hljs-section\">## What happened?\u003C/span>\n\n<!-- Describe the bug clearly and concisely -->\n\n\u003Cspan class=\"hljs-section\">## Steps to reproduce\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">1.\u003C/span> Go to '...'\n\u003Cspan class=\"hljs-bullet\">2.\u003C/span> Click on '...'\n\u003Cspan class=\"hljs-bullet\">3.\u003C/span> See error\n\n\u003Cspan class=\"hljs-section\">## Expected behavior\u003C/span>\n\n<!-- What did you expect to happen? -->\n\n\u003Cspan class=\"hljs-section\">## Environment\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> OS: [e.g. macOS 14]\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> Version: [e.g. 2.1.0]\n\u003C/code>\u003C/pre>\u003Cp>HTML comments (\u003Ccode><!-- -->\u003C/code>) show in the template but are hidden in the rendered output, making them perfect for writing instructions to issue reporters.\u003C/p>\n\u003Ch2 id=\"github-wikis\">GitHub Wikis\u003C/h2>\n\u003Cp>GitHub Wikis use GFM but with notable differences from READMEs:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>No @mentions or #issue auto-links\u003C/strong> — \u003Ccode>@username\u003C/code> and \u003Ccode>#123\u003C/code> are plain text\u003C/li>\n\u003Cli>\u003Cstrong>Separate git repository\u003C/strong> — clone at \u003Ccode>https://github.com/owner/repo.wiki.git\u003C/code>\u003C/li>\n\u003Cli>\u003Cstrong>Custom sidebar\u003C/strong> — create \u003Ccode>_Sidebar.md\u003C/code> for navigation\u003C/li>\n\u003Cli>\u003Cstrong>Custom footer\u003C/strong> — create \u003Ccode>_Footer.md\u003C/code> for a footer on every page\u003C/li>\n\u003Cli>\u003Cstrong>File-based navigation\u003C/strong> — wiki pages link using the page title, spaces replaced with hyphens\u003C/li>\n\u003C/ul>\n\u003Ch3 id=\"wiki-sidebar\">Wiki sidebar\u003C/h3>\n\u003Cp>Create \u003Ccode>_Sidebar.md\u003C/code> for a persistent navigation panel:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-section\">## Documentation\u003C/span>\n\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [[Home]]\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [[Installation]]\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [[Configuration]]\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [[Basic Setup]]\n\u003Cspan class=\"hljs-bullet\">  -\u003C/span> [[Advanced Options]]\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [[API Reference]]\n\u003Cspan class=\"hljs-bullet\">-\u003C/span> [[Troubleshooting]]\n\u003C/code>\u003C/pre>\u003Cp>Wiki page links use double brackets: \u003Ccode>[[Page Name]]\u003C/code> becomes a link to the \u003Ccode>Page-Name\u003C/code> wiki page.\u003C/p>\n\u003Ch2 id=\"alerts\">Alerts and Callouts\u003C/h2>\n\u003Cp>GitHub added native alert support in 2023. These render as styled callout boxes with colored borders and icons:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-quote\">> [!NOTE]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Highlights information that users should take into account, even when skimming.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!TIP]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Optional information to help a user be more successful.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!IMPORTANT]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Crucial information necessary for users to succeed.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!WARNING]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Critical content demanding immediate user attention due to potential risks.\u003C/span>\n\n\u003Cspan class=\"hljs-quote\">> [!CAUTION]\u003C/span>\n\u003Cspan class=\"hljs-quote\">> Negative potential consequences of an action.\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Alerts work in READMEs, Issues, and PRs. Support in Wikis is inconsistent — test before relying on them there. For a deep dive on callout syntax across platforms, see our \u003Ca href=\"/blog/markdown-admonitions-callouts-complete-guide\">Markdown admonitions guide\u003C/a>.\u003C/p>\n\u003Ch2 id=\"diagrams\">Diagrams with Mermaid\u003C/h2>\n\u003Cp>GitHub renders \u003Ca href=\"https://mermaid.js.org/\">Mermaid\u003C/a> diagrams natively using fenced code blocks with the \u003Ccode>mermaid\u003C/code> language identifier:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">\u003Cspan class=\"hljs-code\">```mermaid\ngraph LR\n    A[User] -->|HTTP request| B[Load Balancer]\n    B --> C[App Server 1]\n    B --> D[App Server 2]\n    C --> E[(Database)]\n    D --> E\n```\u003C/span>\n\u003C/code>\u003C/pre>\u003Cp>Mermaid supports:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>Flowcharts\u003C/strong> (\u003Ccode>graph LR\u003C/code>, \u003Ccode>graph TD\u003C/code>)\u003C/li>\n\u003Cli>\u003Cstrong>Sequence diagrams\u003C/strong> (\u003Ccode>sequenceDiagram\u003C/code>)\u003C/li>\n\u003Cli>\u003Cstrong>Gantt charts\u003C/strong> (\u003Ccode>gantt\u003C/code>)\u003C/li>\n\u003Cli>\u003Cstrong>Class diagrams\u003C/strong> (\u003Ccode>classDiagram\u003C/code>)\u003C/li>\n\u003Cli>\u003Cstrong>Entity relationship diagrams\u003C/strong> (\u003Ccode>erDiagram\u003C/code>)\u003C/li>\n\u003Cli>\u003Cstrong>State diagrams\u003C/strong> (\u003Ccode>stateDiagram-v2\u003C/code>)\u003C/li>\n\u003C/ul>\n\u003Cp>For more on embedding diagrams, see our \u003Ca href=\"/blog/markdown-diagrams-flowcharts-complete-guide\">Markdown diagrams guide\u003C/a>.\u003C/p>\n\u003Ch2 id=\"github-pages\">GitHub Pages and Jekyll\u003C/h2>\n\u003Cp>GitHub Pages uses Jekyll to build sites from your repository. Jekyll adds YAML frontmatter and Liquid templating on top of Markdown.\u003C/p>\n\u003Ch3 id=\"yaml-frontmatter\">YAML frontmatter\u003C/h3>\n\u003Cp>Frontmatter goes at the very top of the file, between \u003Ccode>---\u003C/code> delimiters:\u003C/p>\n\u003Cpre>\u003Ccode class=\"hljs language-markdown\">---\ntitle: My Page Title\nlayout: post\ndate: 2026-05-08\nauthor: Jane Smith\n\u003Cspan class=\"hljs-section\">categories: [tutorials, markdown]\n---\u003C/span>\n\nContent starts here.\n\u003C/code>\u003C/pre>\u003Cp>For a full reference on frontmatter options, see our \u003Ca href=\"/blog/markdown-metadata-yaml-frontmatter-complete-guide\">YAML frontmatter guide\u003C/a>.\u003C/p>\n\u003Ch3 id=\"jekyll-vs-plain-github-markdown\">Jekyll vs plain GitHub Markdown\u003C/h3>\n\u003Cp>The critical difference with Jekyll: it runs a \u003Cstrong>Liquid template preprocessor\u003C/strong> over your files before Markdown rendering. This means:\u003C/p>\n\u003Cul>\n\u003Cli>Content between curly braces may be interpreted as template expressions\u003C/li>\n\u003Cli>Code blocks that show templating syntax (Liquid, Jinja, Handlebars, etc.) need special escaping\u003C/li>\n\u003Cli>Wrap problematic code blocks with the \u003Ccode>raw\u003C/code> and \u003Ccode>endraw\u003C/code> Liquid tags to pass content through unprocessed\u003C/li>\n\u003C/ul>\n\u003Cp>This is a common stumbling block when documenting frameworks that use template syntax. Our \u003Ca href=\"/blog/markdown-collapsible-sections-guide\">Markdown collapsible sections guide\u003C/a> has more on \u003Ccode><details>\u003C/code> patterns that also work in Jekyll sites.\u003C/p>\n\u003Ch2 id=\"quick-reference\">Quick Reference\u003C/h2>\n\u003Cp>A few tools that pair well with GitHub Markdown:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-editor\">Markdown Live Editor\u003C/a>\u003C/strong> — preview and edit GFM in real time before committing\u003C/li>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-table-formatter\">Markdown Table Formatter\u003C/a>\u003C/strong> — clean up misaligned tables before pushing\u003C/li>\n\u003Cli>\u003Cstrong>\u003Ca href=\"/tools/markdown-to-html\">Markdown to HTML\u003C/a>\u003C/strong> — see exactly what HTML your Markdown generates\u003C/li>\n\u003C/ul>\n\u003Cp>Related reading:\u003C/p>\n\u003Cul>\n\u003Cli>\u003Ca href=\"/blog/markdown-internal-links\">Markdown internal links and anchors\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-tables-advanced-features-and-styling-guide\">Markdown tables: advanced features and styling\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-collapsible-sections-guide\">Markdown collapsible sections\u003C/a>\u003C/li>\n\u003Cli>\u003Ca href=\"/blog/markdown-platform-compatibility-guide\">Markdown across platforms: what actually works\u003C/a>\u003C/li>\n\u003C/ul>\n",[15,19,22,25,28,31,34,37,40,43],{"id":16,"text":17,"level":18},"table-of-contents","Table of Contents",2,{"id":20,"text":21,"level":18},"what-is-gfm","What is GitHub Flavored Markdown?",{"id":23,"text":24,"level":18},"features-by-surface","Features by Surface",{"id":26,"text":27,"level":18},"readme-best-practices","README Best Practices",{"id":29,"text":30,"level":18},"issues-and-pull-requests","Issues and Pull Requests",{"id":32,"text":33,"level":18},"github-wikis","GitHub Wikis",{"id":35,"text":36,"level":18},"alerts","Alerts and Callouts",{"id":38,"text":39,"level":18},"diagrams","Diagrams with Mermaid",{"id":41,"text":42,"level":18},"github-pages","GitHub Pages and Jekyll",{"id":44,"text":45,"level":18},"quick-reference","Quick Reference",[47,48,49],"markdown-editor","markdown-table-formatter","markdown-to-html",[51,60,68],{"slug":52,"title":53,"description":54,"excerpt":55,"date":56,"category":57,"author":58,"keywords":59,"readingMinutes":12},"markdown-in-obsidian-complete-workflow-guide","Markdown in Obsidian: The Complete Workflow Guide","A practical guide to using Markdown in Obsidian — covering wiki-links, callouts, YAML frontmatter, essential plugins, and real workflows for knowledge management.","Obsidian has grown from a niche note-taking app to one of the most popular tools among developers, writers, and researchers. It’s built entirely around plain Markdown files stored locally — and…","2026-05-01","Guide","Matthew Rathbone","obsidian markdown, obsidian workflow, obsidian wiki-links, obsidian callouts, obsidian plugins, obsidian zettelkasten, obsidian markdown guide, obsidian tutorial",{"slug":61,"title":62,"description":63,"excerpt":64,"date":65,"category":66,"author":10,"keywords":67,"readingMinutes":12},"markdown-for-technical-writers-docs-as-code","Markdown for Technical Writers: The Docs-as-Code Workflow Guide","How to set up a docs-as-code workflow with Markdown, Git, and a static site generator — practical guidance for technical writers moving away from wiki-based tools.","\"Docs-as-code\" is the practice of treating documentation the same way software teams treat code: write in plain text (usually Markdown), version-control in Git, review through pull requests, and…","2026-05-15","workflows","docs as code, markdown technical writing, documentation workflow, markdownlint, vale prose linter, mkdocs markdown, docusaurus technical writing, docs as code workflow",{"slug":69,"title":70,"description":71,"excerpt":72,"date":73,"category":57,"author":58,"keywords":74,"readingMinutes":75},"markdown-platform-compatibility-guide","Markdown Across Platforms: What Actually Works in GitHub, Notion, Obsidian, and Confluence","A practical Markdown compatibility guide for GitHub, Notion, Obsidian, Confluence, VS Code, and more. Includes a feature comparison table and platform-specific tips.","Markdown is everywhere — but Markdown is not the same everywhere. If you've ever carefully written a document with footnotes, custom HTML, or a nice callout block, only to paste it into a…","2026-04-30","markdown compatibility, markdown platforms, github markdown, notion markdown, obsidian markdown, confluence markdown, markdown comparison, markdown features by platform",8,1792184946734]