Markdown on GitHub: Master Issues, PRs, and Documentation

GitHub is a markdown-first platform. Your README files, your documentation, your issues, your pull requests, your discussions—they all use markdown. If you're using GitHub (and most developers are), you're writing markdown every day, whether you realize it or not.

The good news: GitHub-flavored markdown is powerful and expressive. The challenge: many developers and technical writers don't know what's possible beyond basic bold and italics.

Let's fix that.

The Places You Write Markdown on GitHub

READMEs and documentation — The first thing visitors see. Often the only documentation some projects have. Markdown files in your repo or in the /docs folder. See our guide on how to write a README.

Issues and discussions — Bug reports, feature requests, questions, and conversations. All markdown.

Pull requests — The body of a PR description, code review comments, and the merge commit message. Markdown.

Comments — On issues, PRs, discussions, and commits. All markdown.

Wikis and project descriptions — GitHub Pages and project READMEs. Markdown.

For many developers, their daily writing happens entirely in GitHub markdown. Learning to write it well matters.

GitHub-Flavored Markdown (GFM) Features

GitHub uses "GitHub-flavored markdown," which extends standard markdown with some handy features—learn more about markdown extensions like GFM.

Tables

Standard markdown doesn't have native table support. GitHub does—see our markdown tables guide for more details:

| Feature | Free | Pro |
|---------|------|-----|
| Issues | Yes | Yes |
| Projects | Basic | Advanced |
| Actions | 2000 min/mo | Unlimited |

Renders as:

Feature	Free	Pro
Issues	Yes	Yes
Projects	Basic	Advanced
Actions	2000 min/mo	Unlimited

Use pipes to separate columns, hyphens for the header row. GitHub handles the formatting.

Task Lists

Need a checklist in an issue? Use task list syntax:

- [x] Design the feature
- [ ] Write tests
- [ ] Document the changes
- [ ] Deploy to production

This renders as interactive checkboxes. Developers can click the boxes to update the issue without leaving the comment.

Code Blocks With Language Highlighting

Wrap code in triple backticks and specify the language:

function greeting(name) {
  console.log(`Hello, ${name}!`);
}

GitHub syntax-highlights automatically. Works for JavaScript, Python, Ruby, Go, SQL, Bash, and 100+ other languages.

Strikethrough

Wrap text in ~~double tildes~~ for strikethrough. Useful for showing edits or corrections without deleting text.

This is ~~wrong~~ corrected.

Autolinks

One of the most useful GitHub-specific features. Type a reference, and GitHub automatically links it:

#123 links to issue 123
GH-456 links to issue 456
@username links to a user profile
SHA-1234abc links to that commit
Full URLs are auto-linked

Fixed in #789.
Requested by @alice.
See commit abc1234 for details.
Visit https://example.com for more info.

This saves you from writing explicit markdown links. Just reference the issue or commit, and GitHub handles the rest.

Mentions and Teams

Start typing @ and GitHub's autocomplete shows you users and teams:

@octocat can you review this?
@github/security-team please check for vulnerabilities.

Mentioned users get a notification. Useful for pulling in reviewers or notifying teams.

Code References

Reference code directly in comments:

Look at the validation logic in `src/validators.ts:45-60`.

If you include a file path, GitHub makes it a link to the specific lines.

GitHub Alerts (v0.0.1 as of Feb 2026)

GitHub recently introduced "alerts"—a way to highlight important information:

> [!NOTE]
> This is a note. Use for general information.

> [!IMPORTANT]
> This is important. Use for critical information.

> [!WARNING]
> This is a warning. Use for caution or potential issues.

These render as styled callout boxes with colored left borders. Great for breaking out information in READMEs, issue templates, or documentation.

Collapsed Sections

Use HTML <details> and <summary> tags to create collapsible sections:

<details>
<summary>Click to expand installation instructions</summary>

1. Clone the repo: `git clone ...`
2. Install dependencies: `npm install`
3. Run tests: `npm test`

</details>

The summary text is always visible. The content collapses until clicked. Great for long READMEs, troubleshooting sections, or detailed setup instructions.

Best Practices for GitHub Markdown

Write Clear Issue Titles

An issue title should be specific and descriptive. Not "Bug in settings" but "Settings page fails to save user email when @domain is in address."

GitHub searches and filters on issue titles. Make them scannable.

Use Headings to Structure PRs

A big PR description should use headings:

# Changes

Brief summary of what changed and why.

## What This Does

- Adds user authentication
- Validates email addresses
- Stores sessions in Redis

## Testing

How to test these changes:
- Unit tests: `npm test`
- Integration tests: `npm run test:integration`

## Related Issues

Closes #456.
Fixes #789.

## Screenshots

[Attach a screenshot of the UI change]

Reviewers can quickly understand the scope, test approach, and related work.

Reference Related Issues

Use "Closes #123" or "Fixes #456" in PR descriptions. GitHub automatically closes the referenced issue when the PR merges. Keeps your issue tracker clean and links related work.

Use Code Blocks for Configuration

When you're sharing configuration, use code blocks:

Add this to your `.env` file:

\`\`\`bash
DATABASE_URL=postgres://...
API_KEY=your-key-here
\`\`\`

Monospace formatting makes it clear this is something to copy and paste.

Break Up Long READMEs

If your README is more than a few screens long, split it:

# ProjectName

Quick intro, installation, basic usage.

## Documentation

See the [full documentation](./docs/README.md) for:
- Advanced configuration
- API reference
- Troubleshooting
- Contributing guide

Link to separate .md files in a /docs folder. Keeps the main README focused.

Tools for Writing GitHub Markdown

You don't need special tools to write markdown on GitHub—the web interface has a live preview. But for longer documents (READMEs, documentation), consider:

OpenMark — A native macOS markdown editor with live preview. Write your documentation locally with proper syntax highlighting when writing documentation with markdown, then commit it to GitHub.
VS Code — Built-in markdown preview. Good if you're already in your editor.
GitHub's edit interface — Click the edit button on any .md file and you get a split view: edit on the left, live preview on the right.

A Note on Markdown Consistency

One challenge with writing markdown in GitHub's web interface: you lose your personal editor's features. Syntax highlighting, spell-check, formatting shortcuts, live preview.

If you're writing longer documentation (like your README or a contributing guide), write it locally in a markdown editor like OpenMark, preview it properly with all your editor's features, then commit and push to GitHub.

You'll write better documentation this way. Faster, with fewer typos, and with proper formatting.

Next Steps

GitHub markdown is everywhere. The more you master it, the clearer your issues, PRs, and documentation become. Your team will understand what you're asking. Reviewers will find the information they need. New contributors will have better onboarding.

Start small: use task lists in your next issue, tables in your next README, and GitHub alerts to highlight important information.

For longer documentation, write it locally in a proper markdown editor, then push it to GitHub.

Writing good markdown makes you a better communicator. OpenMark is designed to make markdown writing feel natural and fast—with live preview, Mermaid diagram support, and LaTeX math rendering.

Download OpenMark for $9.99 on the Mac App Store.