3.3 Markdown for Issues and Pull Requests

Why Markdown is GH-900's "clear communication" skill

The January 2026 GH-900 outline does not ask you to become a technical writer. It asks you to identify uses of Markdown for clear communication in issues and pull requests. That wording is deliberate. GitHub Foundations is aimed at non-developers, developers, and all GitHub users. The shared language of GitHub is not Java or YAML; it is GitHub Flavored Markdown (GFM) in issue bodies, pull request summaries, review comments, and discussion posts.

Clear communication here means two things at once. First, a human can scan the request: what is broken, what you changed, what is still open. Second, GitHub can act on structured cues: notify a person, autolink a record, close an issue, render a checklist. If you dump an unstructured paragraph into a pull request, reviewers miss the test plan. If you use GFM, the same words become headings, a task list, a fenced log snippet, and Fixes #842.

Markdown is not only for README files. Domain 1 wants you to picture Markdown inside the collaboration UI—the text boxes you use every time you open an issue or request a review. Later domains will reuse the same syntax in wikis, Gists, and comments. Learn it once here.

GitHub Flavored Markdown you must recognize

GFM is Markdown plus GitHub-specific extensions (the GFM spec and GitHub's basic writing docs). You do not need every footnote edge case. You do need the constructs that show up in issues and PRs.

Headings and emphasis

Prefix a line with one to six # characters to make heading levels. Two or more headings in a file produce an Outline table of contents. In comments, headings break a long bug report into "Repro," "Expected," and "Logs" so a maintainer does not drown in a wall of text.

Emphasis uses **bold**, _italic_, ~~strikethrough~~, and nested combinations. Keyboard shortcuts exist in the web editor (Command/Ctrl+B for bold, Command/Ctrl+I for italic). Emphasis is how you mark a breaking change in a PR summary without shouting in all caps.

Lists, nested lists, and task lists

Unordered lists start with -, *, or +. Ordered lists start with numbers. Nested lists indent until the marker lines up under the parent's text (or, in the proportional-font comment editor, count the characters before the parent text and indent at least that far).

Task lists are the exam's favorite list variant. Preface an item with - [ ] for incomplete and - [x] for complete:

- [x] Add regression test
- [ ] Update the changelog
- [ ] Request review from @octo-org/docs

GitHub renders those as checkboxes. Teams use them as acceptance criteria on a pull request or as a triage checklist on an issue. Completing boxes is visible collaboration: you do not need a separate project board to show "tests done, docs not done." If a task description must start with a parenthesis, escape it so GFM does not break the checkbox.

Code, quotes, and colors

Inline code uses single backticks: git status. Fenced code blocks use triple backticks and can carry a language tag for syntax highlighting. Bug reports that paste logs without fences become wrapped, unreadable prose. Bug reports that fence the log let a reviewer copy a stack trace.

Block quotes use >. In a conversation, you can highlight text and press R to quote it, or use Quote reply. Quoted context stops "which comment are you answering?" confusion.

In issues, pull requests, and discussions (not everywhere else), a supported color literal in backticks—#0969DA, rgb(9, 105, 218), hsl(212, 92%, 45%)—renders a color chip. That is a small GFM extra; do not confuse it with CSS knowledge.

Tables, links, and images

Pipe tables are first-class GFM:

| OS | Version | Result |
| --- | --- | --- |
| macOS | 15 | pass |
| Windows | 11 | fail |

A compatibility matrix in a bug issue is clearer as a table than as a sentence.

Links are [text](url). GitHub also autolinks bare URLs. Relative links to other files in the repo (docs/CONTRIBUTING.md) survive clones better than absolute github.com URLs. Images are ![alt text](url). Alt text is not decoration; it is the accessible description. You can drag-and-drop, paste, or browse to upload assets into issues, PRs, comments, and Markdown files.

Mentions, references, keywords, and alerts

Typing @ plus a username or org/team mentions that person or team and triggers a notification, if they have read access (and, for org-owned repos, are members). Mentioning a parent team also notifies child teams. Autocomplete lists collaborators and thread participants so you do not @-spam strangers.

Typing # suggests issues and pull requests; #123 becomes a live reference. Cross-repo references use owner/repo#123. Custom autolinks can shorten Jira or Zendesk keys if an admin configured them.

Closing keywords in a pull request description (or a commit message) link work to an issue and close the issue when the PR merges into the default branch:

Colons and capitalization are allowed (Closes: #10, CLOSES #10). Multiple issues each need the full keyword syntax. If the pull request targets any branch other than the default branch, GitHub ignores the keywords—no link, no auto-close. That single rule is the highest-yield Markdown-plus-workflow trap on GH-900.

Alerts (callouts) are GFM blockquotes that render with color and an icon. The five types are NOTE, TIP, IMPORTANT, WARNING, and CAUTION:

> [!WARNING]
> Do not force-push the default branch.

Use them sparingly for information a skimming reviewer must not miss.

Other GFM extras you should recognize by name: emoji shortcodes (:tada:), footnotes in Markdown files (not wikis), HTML comments to hide content, and backslash escapes when you need a literal *.

How to use GFM inside issues and pull requests

Write issues so a newcomer can act without a meeting. A useful bug issue is not "it broke." It is a heading for the symptom, a fenced log, a table of environments, a task list of what you already tried, and @ the on-call owner. A useful feature issue states the problem, links related issues with #, and lists acceptance boxes.

Write pull requests so a reviewer can decide merge versus request-changes in one screen. GitHub Flow already told you to summarize the change and the problem. GFM is how that summary works: a short heading, a bullet list of behavior changes, a task list of remaining work, screenshots with alt text for UI changes, and Fixes #nnn so the issue closes when the default branch receives the merge.

Draft pull requests still need Markdown. Early feedback is cheaper when the incomplete PR already has a checklist and a warning alert about a known gap.

Line comments on a diff can include suggested changes and fenced snippets. Review conversations that quote the previous remark stay anchored. Saved replies (Domain 5) are often Markdown snippets; the syntax you learn here is the body of those later tools.

Why the exam calls this "clear communication"

GH-900's audience includes people who will never open a terminal. Their contribution is still a written artifact on GitHub. Markdown is the skill that makes that artifact structured. Headings create an outline. Task lists make progress visible. Fences preserve evidence. Tables compare facts. Mentions route the conversation. References connect records. Keywords close the loop when GitHub Flow merges to the default branch.

If you only remember "Markdown is for README files," you will miss questions that place a task list in a pull request or a closing keyword in a PR description. If you remember that GFM is the collaboration language of issues and PRs, the Domain 1 bullet is doing its job.

Exam traps

• Closing keywords in a PR that targets develop or any non-default branch do nothing. The PR must target the default branch.
• Closes 10 without # is not a reference. You need Closes #10 or Fixes owner/repo#10.
• Mentions do not notify people who lack read access, or non-members on an organization repository.
• Task list syntax is - [ ] with a space; -[] will not render a checkbox.
• Alerts are > [!NOTE] (and TIP, IMPORTANT, WARNING, CAUTION), not random HTML.
• Autolinked issue numbers are communication and navigation. Prefer #123 over "the login bug we filed last week."
• Images without alt text fail the "clear" test for anyone using a screen reader and for anyone reading a broken image URL.

If a GH-900 item shows a snippet of issue body and asks what happens, read it as GFM: will GitHub notify, link, check off, or close something, or is it only formatted text?