How to use GitHub Markdown syntax

What this covers

This is a faithful reference-style how-to from Basic writing and formatting syntax: the Markdown constructs GitHub documents for prose and code. No CLI verification labs. Type in the web editor or any Markdown file, then Preview.

flowchart LR
    Source[Raw Markdown Text] --> Parser[GitHub Flavored Markdown Parser]
    Parser --> Elements[Headings, Lists, Quotes & Styling]
    Elements --> Render[Sanitized HTML Output in Preview]

Headings

Add 1-6 # symbols before heading text:

# A first-level heading## A second-level heading### A third-level heading

With two or more headings, GitHub builds a table of contents under the file header Outline control.

Styling text

Keyboard: Command+B / Ctrl+B for bold; Command+I / Ctrl+I for italic (Mac / Windows-Linux). Subscript, superscript, and underline use supported HTML tags as shown in the GitHub docs table.

Quoting text and code

Blockquotes use >:

Text that is not a quote> Text that is a quote

In a conversation, highlight text and type R to quote, or use Quote reply on a comment.

Inline code uses single backticks: `git status`. Fenced blocks use triple backticks (see Creating and highlighting code blocks). Shortcut Command+E / Ctrl+E inserts inline backticks.

Supported color models

In issues, pull requests, and discussions, a color model inside backticks can show a swatch:

The background color is `#ffffff` for light mode and `#000000` for dark mode.

Supported: HEX (#RRGGBB), RGB (rgb(R,G,B)), HSL (hsl(H,S,L)). No leading/trailing spaces inside the backticks. Color visualization is not for plain .md files outside those surfaces.

Links, section links, and relative links

Inline link:

This site was built using [GitHub Pages](https://pages.github.com/).

Shortcuts: Command+K to create a link; with text selected, paste a URL to link the selection. Valid bare URLs often autolink in comments (Autolinked references and URLs).

Section links: hover a rendered heading, click the anchor icon, copy the fragment. Anchors lower-case letters, replace spaces with -, strip other punctuation, and append -1, -2, … for duplicates.

Relative links inside a repo (recommended over absolute):

[Contribution guidelines for this project](docs/CONTRIBUTING.md)

Keep link text on one line. Paths starting with / are relative to the repository root; ./ and ../ work.

Custom anchors: <a></a> then link with [text](#my-custom-anchor-point). Custom anchors do not appear in the Outline.

Line breaks and paragraphs

In issues/PRs/discussions, a single newline often becomes a break. In .md files, use two trailing spaces, a trailing \, or <br /> for a hard break. A blank line always starts a new paragraph.

Images

![Alt text describing the image](https://example.com/image.png)

Prefer relative paths for repo assets. Drag-drop / paste also works (Attaching files). The HTML `` element is supported (see the writing quickstart).

Lists and task lists

Unordered: -, *, or +. Ordered: 1., 2., …. Nest by indenting so the marker aligns under the parent text (Tab / Shift+Tab in the web editor).

Task list:

- [x] #739- [ ] https://github.com/octo-org/octo-repo/issues/740- [ ] Add delight to the experience when all tasks are complete :tada:

Escape a leading parenthesis: - [ ] \(Optional) Open a followup issue. More: About tasklists.

Mentions, issue refs, emoji, uploads

• @username or @org/team notifies people with read access.
• Type # to pick issues/PRs in the repo.
• Custom autolinks (Jira, Zendesk, …) if admins configured them.
• Upload assets via drag-drop, file picker, or paste.
• Emoji: :EMOJICODE: (type : for autocomplete).

Footnotes and alerts

Footnotes:

Here is a simple footnote[^1].[^1]: My reference.

Footnotes always render at the bottom; not supported in wikis.

Alerts (callouts) use special blockquotes. Limit to one or two per article; do not nest:

> [!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.

Comments, escaping, and Code view

Hide content with HTML comments: ``. Escape Markdown with \* etc. Issue/PR titles still format. On a rendered Markdown file, click Code to view source and use line linking.

Quick checks

• After multi-heading edits, open Outline and click a section to confirm anchors.
• For repo-internal navigation, prefer relative paths over absolute https://github.com/... links so clones still work.
• Task lists and color swatches behave differently in .md files vs issue/PR conversations. Match the surface to the feature.
• When a heading changes, update any #section links that pointed at the old anchor.

Further reading

• GitHub Flavored Markdown Spec
• About writing and formatting on GitHub
• Working with advanced formatting
• Quickstart for writing on GitHub