Why this course exists
You've seen markdown even if you've never heard the name - every README on GitHub, every nicely formatted ChatGPT answer, every Notion page is markdown underneath. This course teaches it the only way that sticks: by building something real. Four sessions, one running project - your own page, live on your GitHub profile by the end.
What markdown actually is 6 min live
Markdown is a lightweight markup language: you add a few characters to plain text - # for headings **for bold** - and a processor turns it into a formatted page. The text stays readable BOTH ways. That's the whole trick.
LiveA language you already half-know3 min▶
Markdown's characters aren't arbitrary - they're how people already decorated plain-text email in the 90s: stars for *emphasis*, dashes for lists, > for quoting someone. Markdown just made the old habits official. That's why it feels familiar on day one.
- It's everywhere: GitHub, Reddit, Notion, Obsidian, Slack, Discord, Jupyter, and every major AI chat - one syntax, learned once.
- It's future-proof: a markdown file is plain text; it will open unchanged in 30 years. Word files from 1995 can't say that.
- It's fast: your hands never leave the keyboard - no ribbon, no menus, no hunting for the bold button.
The moment it clicks: you paste your meeting notes into a ChatGPT or Claude chat and the answer comes back with clean headings and bullet lists. That formatting IS markdown - the AI writes it, the chat window renders it. After today you'll write it yourself, and you'll also read AI answers in a whole new way.
LiveBorn 2004, designed to be read2 min story▶
John Gruber released Markdown in 2004 (final version 1.0.1, December 2004), with feedback from Aaron Swartz. The design goal, in Gruber's own words: make it "as readable as possible" - a markdown document should be publishable as-is, as plain text, without looking like it's been marked up with tags.
Compare: HTML needs <strong>bold</strong>, markdown needs **bold**. Both produce the same result - one of them you can still read as you type it. Twenty years later that one decision is why markdown won.
Self-studyFlavors: why markdown differs slightly app to app2 min read▶
Practically every app implements markdown a little differently - these variants are called flavors, like dialects of one language. Two names worth knowing now:
- CommonMark: the standardized core - the basics you learn today work everywhere.
- GitHub Flavored Markdown (GFM): CommonMark plus extras - tables, checklists, emoji shortcodes. Sessions 2-3 territory, and what your profile page will use.
Rule of thumb: the Session 1 elements are universal; anything fancier, check the app. The deep-dive track (DD2) maps the whole flavor landscape if you get curious.
Headings, paragraphs, and the line-break trap 4 min live
Structure first. Two characters - # and the blank line - give a page its whole skeleton.
LiveHeadings: # to ######2 min▶
- One # per level: # is the page title, ## a section, ### a subsection - down to six.
- The space is NOT optional: #Heading silently fails; # Heading works. The #1 beginner bug, and your first quiz question.
- Breathing room: put a blank line before and after each heading - some apps mis-render without it.
LiveParagraphs + the invisible line-break trap2 min▶
Line one. Line two - SAME paragraph!
Blank line = new paragraph.
- Enter once does nothing. Markdown joins consecutive lines into one paragraph. A blank line starts a new one.
- Want a line break WITHOUT a new paragraph? End the line with two spaces, or write <br>. The two-space version is invisible in your editor - the classic trap when a poem or address won't break.
- Never indent paragraphs. Four leading spaces means "code" in markdown - your text would render in a monospace box (Session 2 explains why).
Self-studyHorizontal rules + the underline-style headings2 min read▶
- Horizontal rule: three or more dashes --- alone on a line draw a divider. Keep a blank line above it - text directly above --- turns into a heading instead (see next point).
- Setext headings: the older style - underline text with === for a level-1 or --- for a level-2 heading. You'll see it in the wild; writing # style is cleaner.
- Escaping accidents: a line that starts with a character markdown cares about (like a literal # or -) renders as formatting unless you put a backslash in front: \# not a heading. Full escapable set: \ ` * _ { } [ ] < > ( ) # + - . ! |
Bold, italic, lists, and links 5 min live
The everyday four. Master these plus Part 2 and you can already write 90% of the markdown you'll ever need.
LiveEmphasis: stars do the work1.5 min▶
I love markdown.
I really love it.
It's that good.
- One star = italic, two = bold, three = both. Underscores work too, but stick with stars - they're safer mid-word and everyone reads them.
- Stars hug the text: **bold** works, ** bold ** does not. Openers and closers must match.
LiveLists: dashes and numbers2 min▶
- coffee
- hiking
- data viz
- wake up
- coffee first
- then everything else
- Bulleted: start lines with - (space required after the dash - same rule as headings). * and + also work; pick ONE marker and stay consistent within a list.
- Numbered: 1. with a period, not a parenthesis. Fun fact: the actual numbers don't matter - all 1. renders as 1, 2, 3. Lazy numbering is a pro habit (insert items without renumbering).
LiveLinks: text in brackets, address in parentheses1.5 min▶
- Memory hook: square brackets say it, round brackets take you there - [text](url), no space between them.
- Bare URL in a hurry? Wrap it in angle brackets: <https://example.com> becomes a clickable link.
Self-studyNested lists, reference links, and tidy escaping3 min read▶
- Nested lists: indent the sub-item four spaces under its parent. (Some apps accept two - four is the standard that works everywhere.)
- Reference-style links: keep long URLs out of your sentences - write [my talk][1] in the text and [1]: https://very-long-url... at the bottom of the file. Same rendering, tidier source.
- Links with titles: [text](url "hover text") adds a tooltip.
- Literal stars and dashes: writing about markdown itself, or a filename with underscores? Backslash first: \*not italic\*.
One page, four sessions 2 min live
Every session grows the same file: your about-me page. No toy exercises - in Session 4 this exact document goes live on your GitHub profile, where anyone who looks you up will see it.
Open your editor, type your first markdown ★ 6 min · everyone types
Open stackedit.io/app in a new tab - a free split-pane editor, no account needed. Markdown goes on the left, the rendered page appears on the right. (Backup: dillinger.io - same idea.)
Clear the sample text. Type # followed by your name - watch the right pane produce a big bold heading the instant you type the space.
Press Enter TWICE (blank line!) and write one plain sentence about yourself. Then press Enter once and write another - notice they glue into one paragraph. Add the blank line. Feel the rule.
Bold one word with **stars**, italicize another with *one star*. You're writing markdown.
Draft YOUR about-me page ★ 12 min · everyone builds
Structure first, three headings: # Your Name, then ## About me, then ## Three things I love. Blank lines between everything.
Under "About me": two or three sentences. Who are you, what do you do, what are you learning? Bold the thing you want people to remember; italicize something playful.
Under "Three things I love": a - list, three items. Nobody's grading the hobbies.
Add one real link: your LinkedIn, your favorite site, anything - [text](url). Square brackets say it, round brackets take you there.
Discernment lap: read the RIGHT pane like a stranger would. Reorder, reword, make it yours. This exact file becomes your public page in Session 4 - write like someone will read it, because they will.
A student's first draft was one grey wall of text - technically correct markdown, zero structure. Adding two ## headings and turning one sentence into a three-item list took 90 seconds and made it look designed. Structure IS the design skill, and markdown makes structure cheap.
Break it on purpose ★ 4 min · follow along
Delete the space in a heading: #Broken. Watch the right pane show a sad literal #Broken. Put the space back. (Same trick breaks -item lists.)
Remove the blank line between two paragraphs - watch them merge. Restore it.
Try to type a literal star: write *wink*, see it italicize against your will, then fix it with backslashes: \*wink\*.
Indent a normal sentence four spaces - surprise, it's a grey code box now. Un-indent. You've now met every day-one bug in captivity, on purpose.
This week ◐ 30 min total
- Finish your about-me draft if the session ran short - it's Session 2's starting material. Keep the browser tab open or paste it into any notes app (it's just text!).
- Run the CommonMark tutorial, lessons 1-7 at commonmark.org/help/tutorial - 10 minutes, interactive, covers today's ground with practice exercises.
- Collect for Session 2: a photo URL you like (or your GitHub avatar), one favorite quote, and a list of 4-6 skills with a rough level for each - next week they become an image, a blockquote, and a table.
- Spot markdown in the wild: ask an AI chatbot anything and identify three markdown elements in its answer. They're there.
Three questions before you go 🎯 ◐ 90 seconds
1 · You press Enter once and keep typing - what does markdown do?
Enter once does nothing. Blank line = new paragraph; two trailing spaces or <br> = line break within one.
2 · Why does #Heading render as literal text instead of a heading?
Space after the marker - the same rule saves your lists (- item) too. The #1 beginner bug, now yours to never make.
3 · You want to type a literal * star in your text. Best move?
Backslash escapes any markdown character: \ ` * _ { } [ ] < > ( ) # + - . ! | - the get-out-of-formatting-free card.
Official sources covered
This session teaches the working content of the canonical markdown learning materials - the interactive tutorial at commonmark.org, the reference at markdownguide.org, and the original spec at daringfireball.net.