Markdown and great READMEs
Write GitHub Flavored Markdown - headings, task lists, tables, code, alerts and links to issues - and a README people actually read.
- Write GitHub Flavored Markdown, including tables, task lists and alerts
- Link to issues, pull requests, commits and people with automatic references
- Structure a README that gets new users and contributors going fast
Almost everything you write on GitHub - READMEs, issues, pull requests, comments, wikis - is Markdown: plain text with light punctuation that renders as formatted text. GitHub’s dialect, GitHub Flavored Markdown (GFM), adds tables, task lists and more.
1# Dungeon Dash 🗡️
2
3A retro dungeon crawler with procedurally generated levels.
4
5## Quick start
6
71. Install Python 3.12
82. Run `pip install -r requirements.txt`
93. Start the game with `python -m dungeon_dash`
10
11## Roadmap
12
13- [x] Procedural dungeons
14- [x] Pixel-art hero
15- [ ] Boss battles (see #42)
16- [ ] Co-op mode
17
18| Key | Action |
19| --- | ------ |
20| WASD | Move |
21| Space | Attack |
22
23> [!WARNING]
24> Save files from 0.x won't load in 1.0.
25
26Made with ❤️ by @mira and @sam-sprites.Highlights of GFM:
| Syntax | Renders as |
|---|---|
# Title, ## Section | headings (GitHub builds a table of contents from them) |
**bold**, *italic*, `code` | inline formatting |
| Three backticks plus a language name | a highlighted code block |
- [ ] / - [x] | task list checkboxes - clickable in issues, and counted in progress bars |
| a | b | rows | tables |
> [!NOTE], > [!TIP], > [!WARNING] | colored alert boxes |
#42, mira/pixel-heroes#7, a commit SHA | automatic links to issues, PRs and commits |
@mira, @dungeon-dash/artists | mentions that notify a person or a whole team |
:tada: | 🎉 emoji shortcodes |
A README that works
A README answers, in order, the questions a visitor has:
- What is this? One or two sentences, plus a screenshot or GIF if it’s visual.
- How do I use it? Installation and a minimal example that works when copied.
- Where’s more? Links to docs, the changelog, a demo.
- How do I help? A pointer to
CONTRIBUTING.md, the license, and where to ask questions.
Status badges (little images for build status, version, license) at the top are optional but popular. Keep the README current - an install command that doesn’t work is the fastest way to lose a new user.
1import re
2
3issue_body = """Boss battle checklist
4- [x] Design the dragon sprite
5- [x] Attack patterns
6- [ ] Victory music
7- [ ] Balance testing (see #57)
8"""
9tasks = re.findall(r"^\s*- \[( |x)\] (.+)$", issue_body, flags=re.MULTILINE)
10done = sum(1 for mark, _ in tasks if mark == "x")
11print(f"{done} of {len(tasks)} tasks complete")
12print("referenced issues:", re.findall(r"#(\d+)", issue_body))2 of 4 tasks complete referenced issues: ['57']
Key takeaways
GitHub Flavored Markdown powers READMEs, issues, PRs and comments.
Task lists, tables, alerts and fenced code blocks are GFM extras.
#42, owner/repo#7, commit SHAs and @mentions link and notify automatically.
A good README says what it is, how to use it, where to learn more and how to help.
Lesson quiz
7 questions · pass with 5 correct · up to 50 XP
Passing this quiz completes the lesson and keeps your streak going. Questions you miss come back in review sessions later.
Practice: automate GitHub chores with Python
Real GitHub work involves lots of small automation: matching CODEOWNERS, expanding build matrices, bumping versions, reading the API. Write those helpers in Python and run them against sample inputs - locally in your browser, with no GitHub account needed.
CSV to a Markdown table
The game’s controls live in a CSV file; the README needs them as a GFM table. The first input line is the header. Print a Markdown table with each column padded to its widest cell (left-aligned), and a separator row of dashes the same width:
| Key | Action |
| ----- | ------ |
| WASD | Move |- Controls
- Quoted commas
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Task list progress
The input is an issue body in Markdown. Find its task list items (lines like - [ ] task or - [x] task, possibly indented). Print progress: 2/5 (40%) (percentage rounded to a whole number), then each unfinished task as todo: task text, then mentions: @a, @b - every distinct @mention in order of first appearance - or mentions: none.
- Boss battle
- All done
Python runs in a sandboxed browser worker with a 60 second time limit. Its runtime loads from the Pyodide CDN; your code stays in this browser.
Questions about this lesson
Stuck? Ask. Figured something out? Share it. Explaining is one of the best ways to learn.
Loading posts…