Loading
0x20Lesson 3 of 14

Markdown and great READMEs

Write GitHub Flavored Markdown - headings, task lists, tables, code, alerts and links to issues - and a README people actually read.

22 min 7-question quiz 2 code exercises
By the end of this lesson you can
  • 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.

README.md
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:

SyntaxRenders as
# Title, ## Sectionheadings (GitHub builds a table of contents from them)
**bold**, *italic*, `code`inline formatting
Three backticks plus a language namea highlighted code block
- [ ] / - [x]task list checkboxes - clickable in issues, and counted in progress bars
| a | b | rowstables
> [!NOTE], > [!TIP], > [!WARNING]colored alert boxes
#42, mira/pixel-heroes#7, a commit SHAautomatic links to issues, PRs and commits
@mira, @dungeon-dash/artistsmentions 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:

  1. What is this? One or two sentences, plus a screenshot or GIF if it’s visual.
  2. How do I use it? Installation and a minimal example that works when copied.
  3. Where’s more? Links to docs, the changelog, a demo.
  4. 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.

task_progress.py
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))
Output
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.

Exercise 1

CSV to a Markdown table

+25 XP

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
main.py
Loading editor…

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.

Exercise 2

Task list progress

+25 XP

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
main.py
Loading editor…

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…