Basic Writing and Formatting Syntax (GitHub Docs)

What it is

This page in GitHub Docs explains the Markdown syntax GitHub supports everywhere you write on the platform: README files, issues, pull requests, discussions, comments and wikis. It sits in the Writing on GitHub section, next to separate pages on advanced formatting such as tables, collapsed sections, code blocks, diagrams and mathematical expressions.

Is it worth your time?

Yes, if you use GitHub at all. General Markdown references tell you what is portable; this page tells you exactly how GitHub renders it, and documents GitHub-only behaviour that you will not find elsewhere. That matters for portfolio READMEs, which are often the first thing a recruiter or maintainer reads, and for issues and pull requests, where good formatting gets faster reviews.

What it covers

The page walks through headings, styling text, quoting text and code, supported colour models, links, section links, relative links, custom anchors, line breaks, images, lists, task lists, mentioning people and teams, referencing issues and pull requests, referencing external resources, uploading assets, emoji, paragraphs, footnotes, alerts, hidden comments, and how to ignore or disable Markdown rendering.

A few sections are especially useful:

• Section links: how GitHub builds heading anchors (lowercase, spaces to hyphens, punctuation removed), so tables of contents work.
• Relative links: why links like docs/CONTRIBUTING.md keep working on every branch and fork.
• Alerts: the five callout types (NOTE, TIP, IMPORTANT, WARNING and CAUTION), with GitHub's advice to limit them to one or two per article.
• Task lists and mentions: how checkboxes, @mentions and #123 references behave in issues and pull requests.

How long it takes

Thirty to forty-five minutes to read end to end with the examples. Most people then return to one section at a time.

Prerequisites

A GitHub account helps so you can try examples in an issue or a test repository, but reading needs nothing.

Free or paid?

Free. GitHub Docs are public and the docs source is open on GitHub.

What you can do after it

Write a README with working anchors, relative links and images, use alerts and collapsed sections well, and format issues and pull requests so reviewers can scan them quickly.

Common questions

Where are tables and diagrams? In the linked Working with advanced formatting pages, which cover tables, collapsed sections, code blocks, Mermaid and other diagrams, and math.

Is this the full GitHub Flavored Markdown spec? No. The formal GFM specification is a separate document; this page is the practical guide to how things look on GitHub.