Guide to Markdown Formatting on GitHub

Most of the writing on GitHub is formatted with a handful of symbols. A pound sign makes a heading, two asterisks make bold text, and a hyphen starts a list. Once you can read those symbols, READMEs, issues, and pull request descriptions stop looking like code and start reading like documents. The same handful of marks works almost everywhere text appears on GitHub.

Markdown is a plain-text formatting language. You type normal text with a few marks, and GitHub turns it into clean headings, lists, links, tables, and code blocks. Links use square brackets for the text and round brackets for the address, and code goes inside backticks so it shows exactly as written. It's also the format many AI tools use for their replies, which is why text pasted from a chat often looks right on GitHub straight away. The Write and Preview tabs let you check the result before anyone else sees it, and small mistakes, like a missing space after a pound sign, show up there immediately.

A few symbols cover almost everything you'll need. The goal isn't to memorize syntax but to write text that stays readable both as plain characters and as a formatted page. A heading, a short list, and a link are often all a good issue or README needs.

Markdown as plain-text formatting

Markdown formats text with ordinary characters. Instead of clicking a bold button, a writer types two asterisks on each side of a word, and the page shows it in bold. John Gruber designed it in 2004 so that text stays easy to read even before it's formatted ^[1].

GitHub uses its own version, GitHub Flavored Markdown, which adds tables, task lists, and automatic links ^[2]. Any file ending in .md, like README.md, is a Markdown file, and GitHub shows it as a formatted page when someone opens it.

Plain text also suits version control. A diff of a Markdown file shows exactly which words changed, which isn't possible with a Word document or a PDF. That's a big reason project documentation is so often written in Markdown rather than in a word processor.

Headings and emphasis in Markdown

A heading starts with one to six pound signs followed by a space: one for the largest level, two for the next, and so on. Two asterisks around text make it bold, like **Open daily**, and one asterisk makes it italic ^[3].

The space after the pound signs matters. ## Opening hours becomes a heading, while ##Opening hours shows up exactly as typed, symbols and all. It's one of the most common formatting slips, and it's easy to miss in plain text because both lines look almost the same.

Headings do more than make text bigger. When a file has two or more of them, GitHub builds a table of contents from them, available from the Outline menu, so a long README can be navigated like a document. Clear headings make that outline worth using.

Lists and task lists

A list item starts with a hyphen and a space, one item per line, and numbers followed by a period make a numbered list. Indenting an item nests it under the one above, which helps break a step into smaller parts.

A task list adds checkboxes. Starting an item with - [ ] creates an empty box, and - [x] creates a checked one ^[4]. In issues and pull requests, the boxes can be ticked right on the page, without editing the text, so a task list doubles as a progress tracker for a bigger job.

Lists make long requests easier to act on. A bug report with numbered steps to reproduce the problem, or a pull request with a checklist of what's done and what's left, saves reviewers from hunting through paragraphs for the important parts.

Links, @mentions, and images

A Markdown link has two parts: the visible text in square brackets and the address in round brackets, like [Spring menu](https://sweetcrumbs.com/menu). GitHub also turns plain web addresses into links automatically, but descriptive link text is easier to read than a long URL.

Images use the same pattern with an exclamation mark in front: ![Cupcake display](images/display.jpg). The text in brackets is the alt text^[5], which screen readers announce and which appears if the image fails to load, so it should describe what the image shows.

GitHub adds two shortcuts of its own. Typing @ followed by a username mentions that person and notifies them, and typing # followed by a number links to that issue or pull request, like #12. Together they connect a conversation to the people and the work it's about.

Inline code and code blocks

Code, file names, and settings are easiest to read in a monospaced font that shows every character exactly. Single backticks around a short snippet format it as inline code within a sentence, like style.css or main.

Longer snippets go in a code block, with a line of three backticks before and after the code. Adding a language name right after the opening backticks, like html or css, turns on syntax highlighting, which colors tags, properties, and values so the code is easier to scan ^[6].

Backticks also protect text from Markdown itself. Inside them, asterisks and pound signs stay as typed instead of turning into bold text or headings. That makes code formatting the right choice for an error message, a configuration value, or a snippet pasted from an AI tool.

Pro Tip! Using diff as the language colors lines that start with a plus in green and lines that start with a minus in red.

Tables in Markdown

Tables are built from pipes and hyphens. The first row holds the column headers, separated by vertical bars. The second row is a line of hyphens under each header, at least three per column, which tells GitHub that the row above is a header. Every row after that becomes a row of the table ^[7].

Colons in the hyphen row set the alignment: a colon on the left aligns a column left, on the right aligns it right, and on both sides centers it. The pipes don't need to line up in the source, though lining them up makes the plain text easier to review.

Tables suit short, structured information, like opening hours by day, pages and their owners, or options with their pros and cons. Long paragraphs inside cells quickly become hard to read, both in the source and on the page.

Pro Tip! A table needs a blank line before it. Without one, GitHub shows the pipes as plain text instead of a table.

Write and Preview tabs

Comment boxes on GitHub, from issues to pull request reviews, have two tabs. Write shows the plain Markdown as it's typed, and Preview shows how it will look once posted ^[8]. Switching between them is the quickest way to check formatting before anyone else sees it.

Above the text sits a formatting toolbar with buttons for headings, bold, lists, links, and more. Each button inserts the same Markdown symbols a writer could type by hand, so the toolbar doubles as a way to learn the syntax: adding bold and watching two pairs of asterisks appear teaches the pattern quickly.

The preview catches mistakes before they reach anyone's inbox. A missing space after a pound sign, a link with a broken bracket, or a table without its row of hyphens is obvious in the preview and easy to miss in plain text. Fixing it before posting saves an edit and a second notification for everyone watching.

Where Markdown is used on GitHub

Markdown works almost everywhere people write on GitHub. README files and other .md files render as pages, and issues, pull requests, review comments, discussions, and wikis accept the same syntax ^[9].

Some fields don't render it. Commit messages appear in the history as plain text, so asterisks and pound signs show up exactly as typed. The short description under a repository's name is plain text, too. Formatting in those places only adds clutter.

Knowing the boundary keeps text clean. A long explanation belongs in a pull request description, where headings and lists render, while the commit message stays a short, plain summary. The same rule makes AI-written commit messages worth a glance, since generated text often arrives full of Markdown symbols.

Markdown in AI-generated content

Most AI chat tools format their replies in Markdown, so a reply pasted into an issue or README usually keeps its headings and lists. The convenience comes with a habit worth correcting: generated text tends to over-format.

Typical signs include:

• Headings above sections only two sentences long
• Bold on every other phrase, so nothing stands out
• Nested bullets where one short paragraph would read better
• Code blocks labeled with the wrong language

A pass in the Preview tab fixes most of it. Removing extra headings, trimming bold, and checking that links point where they should turn generated text into something teammates will actually read. Pasted into a plain-text field, like a commit message, the same reply shows every symbol, so it needs rewriting rather than tidying.