Intermediate

GitHub Flavored Markdown

Master GitHub-specific Markdown features: README best practices, syntax highlighting, alerts/callouts, autolinks, mentions, and GitHub Pages.

What is GFM?

GitHub Flavored Markdown (GFM) is GitHub's extension of standard Markdown. It adds features that are essential for software development workflows: syntax highlighting, task lists, tables, autolinks, and more. GFM is used everywhere on GitHub — READMEs, issues, pull requests, comments, wikis, and discussions.

README.md Best Practices

Your README.md is the front page of your project. A great README should include:

README.md Template
# Project Name

Short description of what this project does
and who it is for.

## Features

- Feature one with brief description
- Feature two with brief description
- Feature three with brief description

## Quick Start

```bash
# Install
npm install my-project

# Run
npx my-project start
```

## Documentation

Link to full docs or include key sections.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md)

## License

[MIT](LICENSE)

Syntax Highlighting

GFM supports syntax highlighting for virtually every programming language. Specify the language after the opening triple backticks:

Language-Specific Code Blocks
```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

```javascript
const greet = (name) => `Hello, ${name}!`;
```

```sql
SELECT name, email FROM users WHERE active = true;
```

```diff
- old line that was removed
+ new line that was added
```

Alerts / Callouts

GitHub supports special blockquote syntax for callout boxes. These are widely used in documentation:

GitHub Alerts
> [!NOTE]
> Useful information that users should know,
> even when skimming content.

> [!TIP]
> Helpful advice for doing things better or
> more easily.

> [!IMPORTANT]
> Key information users need to know to
> achieve their goal.

> [!WARNING]
> Urgent info that needs immediate user
> attention to avoid problems.

> [!CAUTION]
> Advises about risks or negative outcomes
> of certain actions.

Autolinks

Markdown
# URLs become clickable automatically
Visit https://github.com for more info.

# Issue and PR references
#123         Links to issue/PR #123
GH-123       Alternative format

# Cross-repo references
owner/repo#123  Links to issue in another repo

# @mentions
@username    Mentions a user (sends notification)
@org/team    Mentions an entire team

# SHA references
a1b2c3d      Links to a specific commit

Task Lists in Issues and PRs

Task lists in GitHub issues and pull requests are interactive — you can check and uncheck them directly in the rendered view. GitHub also shows progress in the issue list.

Issue with Task List
## Release Checklist

- [x] Update version number
- [x] Run full test suite
- [x] Update CHANGELOG.md
- [ ] Create release notes
- [ ] Tag release in git
- [ ] Publish to npm
- [ ] Announce on social media

# GitHub shows: 3/7 tasks completed

GitHub Profile README

Create a special repository with the same name as your GitHub username to display a README on your profile page:

Profile README Example
# Hi there, I'm Jane 👋

## About Me
Full-stack developer passionate about AI and
open source. Currently building tools for
developer productivity.

## Tech Stack
![Python](https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white)
![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white)
![React](https://img.shields.io/badge/-React-61DAFB?logo=react&logoColor=black)

## GitHub Stats
![Stats](https://github-readme-stats.vercel.app/api?username=janedoe&show_icons=true)

GitHub Pages

GitHub Pages lets you publish Markdown files as a website directly from your repository. It uses Jekyll (a static site generator) to convert Markdown to HTML.

  1. Create a repository

    Name it username.github.io for a personal site, or enable Pages on any repository.

  2. Add Markdown files

    Your index.md or README.md becomes the homepage. Other .md files become pages.

  3. Enable GitHub Pages

    Go to Settings > Pages and select your source branch. Choose a Jekyll theme if desired.

  4. Publish

    Your site is live at https://username.github.io. Updates deploy automatically on push.

✅
Pro tip: Use GitHub's built-in badges to add status indicators to your README: build status, code coverage, version number, license, and download counts. Services like shields.io provide customizable badge images that update automatically.