Session 16: Coach notes

Goal of this session

At the end of this session a ninja can:

• Create a .md file and open it in an editor.
• Write headings, paragraphs, bold, italic and strikethrough text.
• Make numbered and unnumbered lists (including nested lists).
• Make external links and internal links.
• Build a table with columns and alignment.
• Use code blocks with syntax highlighting.
• Write a complete README.md that combines headings, lists, links and code.

Preparation (30 min before the session)

• Editor with Markdown preview ready. VS Code is ideal (built-in preview with Ctrl+Shift+V). Obsidian works too. If nothing is available: use an online editor such as dillinger.io or stackedit.io. Make sure the preview is visible on the projector.
• Demo file ready. Make a demo.md with examples of every Markdown feature (heading, list, link, table, code block). Use it to show live what Markdown looks like as plain text and as preview.
• Thonny as fallback. If ninjas have nothing else: Thonny opens .md files as plain text. They can learn the syntax without a preview; the preview is nice but not essential.

Schedule (3 hours)

Common questions

“Do I have to learn Markdown by heart?” No. Most editors have buttons for formatting (like Word). But knowing the syntax is handy: you type faster, and on platforms like GitHub you only have the plain text.

“What’s the difference between Markdown and HTML?” HTML is for browsers: complicated, with tags like <h1>, <p>, <a href="">. Markdown is for people: simple, readable as text. Under the hood Markdown is converted to HTML. But you never have to write HTML.

“Can I use Markdown in Word or Google Docs?” Not directly. Word uses its own formatting. But you can write Markdown in a .md file and convert it later to PDF, HTML, or Word. Tools like Pandoc do that.

“Why is it called Markdown?” It’s a play on “markup” (markup language). Markdown = “markup” but “down”: simpler, less fuss.

Hints for Stretch and Expert

Stretch: nested lists: Indenting two spaces is enough for a sub-list. Four spaces works too. Being consistent matters more than how many spaces.

Expert: Markdown in Git: Combine this session with session 11: make a README.md, put it in a Git repository, and commit it. Your first Markdown document under version control.

Practical pitfalls

1. Forgetting the blank line before a list. A list has to be preceded by a blank line, otherwise Markdown sticks it onto the previous paragraph. This is the biggest source of “why doesn’t my Markdown work?”

2. Spaces in formatting. ** bold ** doesn’t work: no spaces between the asterisks and the text. **bold** does. This takes getting used to for anyone used to Word.

3. Aligning tables. The : in the separator line (:---, :---:, ---:) determines left/centre/right alignment. A common mistake is forgetting this : and then complaining that the table doesn’t line up.