Markdown for GitHub: README, Issues, and Pull Requests

GitHub is where most developers encounter Markdown for the first time. README files, issue descriptions, pull request bodies, comments, and wiki pages all use GitHub Flavored Markdown (GFM). Writing good Markdown on GitHub makes your projects more professional, your issues clearer, and your PRs easier to review. GitHub hosts over 420 million repositories, making GFM one of the most widely read writing formats in software development.

Quick Answer: GitHub Flavored Markdown (GFM) extends standard Markdown with task lists, tables, strikethrough, autolinked URLs, @mentions, and syntax-highlighted code blocks. Use it to write structured READMEs, clear issue templates, and scannable PR descriptions. GitHub renders GFM natively in every repository with no configuration needed.

What Is GitHub Flavored Markdown (GFM)?

GFM extends standard Markdown with features specifically useful for software development:

• Task lists (- [ ] / - [x])
• Tables
• Strikethrough (~~text~~)
• Autolinked URLs
• Syntax-highlighted code blocks
• Emoji shortcodes (:rocket: renders as a rocket emoji)
• @mentions and #references
• Footnotes (supported since 2021)
• Collapsed sections using <details> and <summary> HTML tags

GFM is a superset of CommonMark, the standardized Markdown specification. This means any valid CommonMark document is also valid GFM. For a complete reference to GFM-specific syntax, see the GitHub Flavored Markdown guide.

How Do You Write a Great README on GitHub?

Your README is the first thing visitors see. It should answer three questions immediately: what does this project do, how do I use it, and how do I install it.

# Project Name

Brief description of what this project does and why it exists.

## Installation

\`\`\`bash
npm install your-package
\`\`\`

## Usage

\`\`\`javascript
import { something } from 'your-package';
something();
\`\`\`

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines.

## License

MIT

Keep it scannable. Use headings, code blocks, and short paragraphs. A wall of text will drive people away.

Additional README best practices:

• Add a badge row (build status, npm version, license) immediately after the project title
• Include a screenshot or animated GIF for UI-based projects. A GitHub analysis found that repositories with screenshots or GIFs in their README receive on average 40% more stars than those without visual content.
• Link to a CHANGELOG.md so users can see what changed between versions
• State the minimum runtime or language version required (Node.js 18+, Python 3.10+, etc.)

For a deeper dive into README structure and formatting for different project types, see the technical documentation with Markdown guide.

How Do You Structure GitHub Issue Templates?

Well-structured issues get resolved faster. Use Markdown formatting to make bug reports and feature requests clear.

Bug Report

## Bug Description

The export button does not generate a PDF on Safari 17.

## Steps to Reproduce

1. Open the editor
2. Write some Markdown content
3. Click the printer icon
4. Select "Save as PDF"

## Expected Behavior

A PDF file should be downloaded.

## Actual Behavior

Nothing happens. No error in the console.

## Environment

- Browser: Safari 17.4
- OS: macOS 14.3

Feature Request

## Problem

There is no way to export documents as DOCX files.

## Proposed Solution

Add a "Download as .docx" option next to the existing .md and .html export buttons.

## Alternatives Considered

- Copy-paste into Google Docs (loses formatting)
- Use Pandoc locally (requires installation)

GitHub supports .github/ISSUE_TEMPLATE/ directories where you can store multiple template files. When a contributor opens a new issue, they see a menu of available templates. Teams that use issue templates report faster triage times because reporters include the required context upfront.

How Do You Write a Good Pull Request Description in Markdown?

A good PR description helps reviewers understand the context before reading the code.

## Summary

Adds dark mode support to the preview pane.

## Changes

- Added `dark` class toggle to the preview container
- Created dark theme CSS variables
- Updated syntax highlighting to use GitHub dark colors

## Screenshots

| Light | Dark |
| ----- | ---- |
| (screenshot) | (screenshot) |

## Testing

- [x] Tested in Chrome, Firefox, Safari
- [x] Verified print output is not affected
- [ ] Accessibility audit pending

The task list in the Testing section is particularly useful. GitHub renders - [x] as a checked checkbox and - [ ] as an unchecked checkbox. Reviewers can see completion status at a glance without opening the PR body. Checked items are also counted in the GitHub PR sidebar. For a complete reference on task list syntax, nesting, and editor support, see the Markdown task lists guide.

How Do You Use Callout Blocks on GitHub?

GitHub supports alert-style callout blocks in Markdown:

> [!NOTE]
> This feature requires Node.js 18 or later.

> [!WARNING]
> This is a breaking change. Update your configuration before upgrading.

> [!TIP]
> Use `--dry-run` to preview changes before applying them.

These render as colored callout boxes, making important information stand out in documentation and issue descriptions. GitHub supports five alert types: NOTE, TIP, IMPORTANT, WARNING, and CAUTION, each with a distinct color and icon.

How Do You Link to Specific Code Lines on GitHub?

Reference specific lines in a file by appending #L10 or #L10-L20 to the file URL. GitHub renders these as syntax-highlighted code snippets when pasted in issues or PRs.

You can also use permanent links (press y on any file page) to ensure the link always points to the same commit, even if the file changes later. Permanent links are critical for issue references that must remain valid after code is refactored. A non-permanent link to a file will break or point to incorrect code after the next push to that branch.

Tips for Better GitHub Markdown

• Use code blocks for commands. Wrap shell commands and code in fenced code blocks with the language specified.
• Add screenshots. Drag and drop images directly into GitHub issues and PRs.
• Use task lists for progress. Reviewers can see at a glance what is done and what remains.
• Keep paragraphs short. GitHub renders Markdown in a narrow column. Long paragraphs are hard to read.
• Link to related issues. Use #123 to reference issues and @username to mention people.
• Use collapsed sections for long outputs. Wrap stack traces or verbose logs in <details><summary>Click to expand</summary>...</details> to keep issue comments readable.

Draft Your GitHub Content in edtr.md

edtr.md supports all GFM features including task lists, tables, callout blocks, and syntax highlighting. Draft your README, issue templates, or PR descriptions in edtr.md with live preview, then paste the Markdown into GitHub.

If you are new to Markdown syntax and want a structured introduction before working with GitHub, the Markdown for beginners guide covers all the fundamentals with examples.