# Markdown The markup behind every README, every Discord message and every answer a chatbot gives you. An hour to learn, years of use. Multimedia & Creative Technology · 0.0 General · Self-study · version 1.0.1 · 2026-09-30 Tags: markdown, github Slides: Speaker notes: ## Agenda 1. Why markdown: Formatting you type 2. The basics: Headings, text, lists, links 3. Playground: Type and watch 4. GitHub flavored: Tables, tasks, alerts 5. In practice: README, Discord, Obsidian, PDF 6. Practice: Drills, quiz, write it yourself ## Self-study: How to work through this *45 minutes, On your own* Set aside three quarters of an hour. The syntax slides are reference, the playground and the drills are the real work. 1. Retype every example in the playground, change something and watch what flips 2. The eight drills are at the end. They are finished when all the dots are green 3. Two quizzes along the way: answer first, read the explanation after 4. Finish with a text of your own in markdown ## 1. Why markdown *Formatting you type instead of click, and that is still readable ten years from now.* **Formatting without buttons.** You put a few characters around your text. A renderer turns them into HTML. The file itself stays plain text that any editor opens. ### Where you run into it - The `README.md` of every project on GitHub - Discord, Slack and Teams: your messages are markdown - Notion, Obsidian, Bear and most note-taking apps - Answers from ChatGPT and Claude arrive in it - Documentation sites, blogs, changelogs - Issues, pull requests and code reviews > [!NOTE] > **One syntax, everywhere** > > What differs between those tools are the extras. The basics are the same everywhere. ### From characters to HTML *A renderer reads your characters and puts HTML tags in their place.* ### Why not Word #### Word and Google Docs - The formatting hides in a binary file - A diff is unreadable, comparing versions fails - Pasting into the web gives you junk HTML - Your mouse does the work #### Markdown - Plain text, any editor opens it - Git sees line by line what changed - The same file becomes HTML, PDF or slides - Your hands stay on the keyboard ### Where it comes from *John Gruber wrote it to keep email readable. Twenty years later it sits in every tool.* - **2004** Markdown 1.0: John Gruber and Aaron Swartz - **2012** Dialects everywhere: Every tool its own variant - **2014** CommonMark: A strict spec, finally - **2017** GitHub Flavored: Tables, tasks, autolinks - **now** Everywhere: From chatbots to static sites ### What is inside a .md file? - A. Plain text - B. HTML - C. A binary format like .docx - D. JSON **Answer:** A. Plain text Plain text with a handful of agreed characters. The tool that shows it turns them into HTML. That is why a .md file opens anywhere, Notepad included. ## 2. The basics *Ten characters that cover ninety percent of what you write.* ### Headings *One to six hashes, followed by a space.* > [!WARNING] > Without the space after the hash nothing happens. `#Title` stays plain text. One `#` per file is enough, that is your page title. ### Paragraphs and line breaks *A blank line starts a new paragraph. A single enter does nothing.* > [!TIP] > Two spaces at the end of a line do the same thing, but you cannot see them sitting there. The backslash you can. ### Bold, italic, struck through *Asterisks and underscores do the same job. Pick one and stick with it.* > [!TIP] > Asterisks always work. Underscores break halfway through a word, think of `snake_case_names`. ### Code inside a sentence *Backticks around a command, a filename or a piece of code.* ### Lists *A dash for a bullet, a number with a dot for an ordered list.* > [!TIP] > The numbers do not have to be right. Write `1.` three times and the renderer counts for you. That saves work when you insert a step later. ### Nesting and task lists *Two spaces of indentation make a sublevel. Brackets turn an item into a checkbox.* > [!WARNING] > Task lists are GitHub territory. In an issue you can tick them with the mouse, and GitHub counts how many are done. ### Links *Text between square brackets, the address between round ones.* > [!TIP] > Good link text says where it goes. The word "here" says nothing, and a screen reader reads out the link on its own. ### Images *The same syntax as a link, with an exclamation mark in front.* > [!NOTE] > The text between the brackets is the alt text: for screen readers, and for everyone whose path turns out to be wrong. ### Quotes *A greater-than sign in front of the line. Works across several paragraphs too.* ### Code blocks *Three backticks, the language behind them, three backticks to close.* > [!TIP] > The language name is what gives you the colours. Leave it out and you get grey text. `js`, `php`, `bash`, `json`: GitHub knows hundreds. ### Tables *Pipes between the columns, a row of dashes under the headers.* > [!TIP] > The pipes do not have to line up, that is only for your own eyes. With `:---` or `---:` you align a column left or right. ### Rules and escaping *Three dashes draw a line. A backslash turns a character back into plain text.* ### Which line makes a second level heading? - A. ## Section - B. \*\*Section\*\* - C. 2. Section - D. == Section == **Answer:** A. ## Section The number of hashes is the level, from 1 to 6. The space after them is required. ### Playground ## 3. GitHub flavored *The extras GitHub puts on top of the standard. Half of them have been copied everywhere by now.* ### What GFM adds *CommonMark is the strict base. GitHub Flavored Markdown puts a layer on top of it.* - **Tables**: Pipes and dashes, with alignment per column. - **Task lists**: Boxes you tick with the mouse inside an issue. - **Strikethrough**: Two tildes around the text. - **Autolinks**: A bare address becomes clickable by itself. - **Footnotes**: References at the bottom of the page. - **Alerts**: Coloured boxes for a warning or a tip. ### Alerts *A quote with a label in front. GitHub draws a coloured box around it.* > [!NOTE] > Five kinds: NOTE, TIP, IMPORTANT, WARNING and CAUTION. They work in READMEs, issues and discussions. ### Emoji, mentions and references *These three only work on GitHub itself, not in any old renderer.* | What you type | What GitHub makes of it | | --- | --- | | `:tada:` | 🎉, and there are a thousand more | | `@sam` | A link to the profile, with a notification | | `#42` | A link to issue or pull request 42 | | `a1b2c3d` | A link to that commit | | `Closes #42` | Closes issue 42 when the pull request is merged | ### Diagrams inside a code block *A code block with mermaid as its language becomes a drawn diagram on GitHub.* ````md ```mermaid flowchart LR A[Working directory] --> B[Staging] B --> C[Repository] C --> D[GitHub] ``` ```` > [!NOTE] > Works in READMEs, issues and discussions, and in Notion and Obsidian through a plugin. In a plain renderer it stays a code block. ### Front matter *A block of YAML between three dashes, at the very top of the file.* ```md --- title: Learning markdown date: 2026-09-20 tags: [docs, basics] draft: false --- # Learning markdown The text starts here. ``` > [!NOTE] > Astro, Hugo, Jekyll, Docusaurus and Obsidian read that block: title, date and tags end up in your site or in your notes. ### Flavours *The same base, different extras. Knowing which flavour you are looking at saves frustration.* | Flavour | Where | What you get extra | | --- | --- | --- | | CommonMark | The strict spec | Nothing extra, everything precisely defined | | GitHub Flavored | GitHub, GitLab, Gitea | Tables, tasks, alerts, autolinks | | MDX | Astro, Docusaurus, Next | React components in between your text | | Obsidian | Notes | Wikilinks, tags, its own callouts | | Discord | Chat | Spoilers, no tables or images | ### HTML in between your markdown *When markdown cannot do it, you are allowed to write HTML. GitHub lets a limited set through.* ```md
Installation on Windows The explanation that only shows up after a click.
Logo ``` > [!WARNING] > GitHub strips out scripts and styles. And markdown inside an HTML tag only works with a blank line in between, like in the example. ## 4. In practice *Where you need markdown this week.* ### What belongs in a README - The name and one sentence: what is it, who is it for - A screenshot or a gif, so nobody has to guess - Installation: commands that work on an empty machine - Usage: the smallest example that does something - The scripts and the configuration - Licence and credits > **Who are you writing for?** > > For yourself in three months, for the lecturer opening your project, and for the employer scrolling your GitHub. ### A README that does the job *Forty lines of markdown, and everyone knows what you built.* ### Discord and Slack *Chat uses the same characters, with a shorter list.* #### Works - `**bold**`, `*italic*`, `~~struck~~` - Inline `` `code` `` and code blocks with a language - Quotes with `>`, across several lines too - Spoilers with `||hidden||` - Lists, recently numbered ones as well #### Does not work - Tables - Images through markdown, you drag them into the window instead - Headings with hashes in Slack, Discord does know them - HTML ### Notes in Obsidian *Markdown files in a folder on your own disk. No database, no subscription, no lock-in.* ```md --- tags: [school, git] --- # Git basics See [[Terminal commands]] for the shell. > [!tip] Shortcut > Cmd+E switches between source and preview. - [ ] Finish the exercise before Friday ``` > [!TIP] > The double brackets are Obsidian, not standard markdown. Anywhere else they stay there as text. Everything you type in Obsidian also opens in VS Code. ### From markdown to something else *The same .md file, different output. There is a tool for each of these three.* - **A PDF**: Write a report in markdown and run it through a converter. No fight with formatting in Word. - **A website**: Blogs and documentation sites often run on a folder of .md files. - **Slides**: A presentation can be a markdown file as well. ### Why a chatbot spits out markdown - The model was trained on GitHub, Stack Overflow and documentation, all markdown - Formatting in plain text fits in the same stream of tokens as the rest of the answer - The chat interface renders it, so you see headings and lists - Paste the answer into your README and the formatting is already right ## 5. Practice *Eight drills, two quizzes and a text of your own.* ### Drills *Type on the left until the right hand side matches the target above it.* ### Why do `First line` and `Second line` end up next to each other? - A. There is no blank line between them - B. Markdown has no line breaks - C. The lines are too short - D. A dash is missing **Answer:** A. There is no blank line between them A single enter is just a space to a renderer. A blank line starts a new paragraph, a backslash or two spaces make a line break inside the same paragraph. ### What does a list that starts with `1.` three times show? - A. 1, 2, 3 - B. Three times 1 - C. An error - D. Bullets **Answer:** A. 1, 2, 3 The renderer counts for you, the first number decides where it starts. That is why you can insert a step without renumbering the rest. ### Cheat sheet *Everything you need day to day, on one screen.* ### Task: Write something in markdown *15 minutes, On your own* Take something you have to write down anyway: notes from a class, a recipe, the explanation of a project. 1. A title and two sections with a subheading 2. A list and a table 3. A link, and a command or piece of code 4. A quote or an alert 5. Type it in VS Code and save it as notes.md ### Further reading *Three sources worth your time, and a spec for when you want to know exactly.* - **[markdownguide.org](https://www.markdownguide.org/)**: The best overview, with a cheat sheet and the differences per tool. - **[commonmark.org](https://commonmark.org/)**: The spec, with a live editor that shows you the parser at work. - **[docs.github.com](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)**: Basic writing and formatting syntax: everything GitHub puts on top. - **[marp.app](https://marp.app/)**: Slides out of markdown, without PowerPoint. ## Glossary - **Markdown**: A markup language in plain text. You put a few agreed characters around your text and a renderer turns them into HTML. John Gruber and Aaron Swartz came up with it in 2004. (slide 9) - **Renderer**: The program that reads your markdown and puts HTML tags in place of the characters. The .md file itself stays plain text that any editor opens. (slide 7) - **CommonMark**: The strict spec of markdown, since 2014. Nothing extra, but everything precisely defined. The other flavours put their extras on top of it. (slide 32) - **GitHub Flavored Markdown**: GFM. The layer GitHub puts on top of CommonMark: tables, task lists, strikethrough, autolinks, footnotes and alerts. GitLab and Gitea use it too. (slide 27) - **Flavour**: A variant of markdown: the same base, different extras. Know which flavour you are looking at, because a table works on GitHub and not in Discord. (slide 32) - **MDX**: Markdown with React components in between your text. Astro, Docusaurus and Next use it. (slide 32) - **Heading**: One to six hashes followed by a space, the number of hashes is the level. Without the space #Title stays plain text. One # per file, that is your page title. (slide 12) - **Line break**: A single enter counts as a space to a renderer, a blank line starts a new paragraph. A line break inside the same paragraph takes a backslash at the end of the line. (slide 13) - **Inline code**: Backticks around a command, a filename or a piece of code inside a sentence: \`npm run dev\`. (slide 15) - **Code block**: Three backticks with the language name behind them, then the code, and three backticks to close. The language name (js, php, bash) gives you the colours, without it you get grey text. (slide 21) - **Task list**: A list with \[ \] or \[x\] right after the dash. On GitHub you tick them with the mouse inside an issue, and GitHub counts how many are done. (slide 17) - **Alt text**: The text between the square brackets of an image: !\[alt text\](path). For screen readers, and for everyone whose path turns out to be wrong. (slide 19) - **Table**: Pipes between the columns and a row of dashes under the headers. With :--- or ---: you align a column left or right. Discord does not know them. (slide 22) - **Escaping**: A backslash in front of a character, so it stays plain text. With \\\* an asterisk stays an asterisk, with \\# the line does not become a heading. (slide 23) - **Alert**: A quote with a label in front, like > \[!NOTE\], that GitHub draws as a coloured box. There are five: NOTE, TIP, IMPORTANT, WARNING and CAUTION. (slide 28) - **Front matter**: A block of YAML between three dashes, at the very top of a .md file. Astro, Hugo, Jekyll and Obsidian read the title, date and tags from it. (slide 31) - **Mermaid**: A code block with mermaid as its language, which GitHub draws as a diagram. In a plain renderer it stays a code block. (slide 30) - **Wikilink**: A link to another note between double square brackets: \[\[Terminal commands\]\]. That is Obsidian, not standard markdown, anywhere else it stays plain text. (slide 38) - **README**: The README.md file of a project: what it is and who it is for, a screenshot, installation, usage and the scripts. So nobody opening your project has to guess. (slide 35) ## Links and sources ### In the deck - [markdownguide.org](https://www.markdownguide.org/) (slide 47) - [commonmark.org](https://commonmark.org/) (slide 47) - [docs.github.com](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) (slide 47) - [marp.app](https://marp.app/) (slide 47)