Advanced Markdown Features

By the end of this lesson you'll write GitHub-Flavoured Markdown like a maintainer: footnotes, collapsible sections, escaped characters, raw HTML, anchor-link tables of contents, badges, emoji, and highlighted code — everything a polished README needs.

1. Footnotes

A footnote lets you add a note without cluttering your sentence. You drop a marker like [^1] where the note belongs (the reference), then define it on its own line as [^1]: text (the definition). The label can be a number or a word — what matters is that the reference and definition use the exact same label. When rendered, the marker becomes a small superscript link, and all the notes collect at the bottom of the page.

Markdown was created in 2004[^1] and is now everywhere[^docs].

You can even put a footnote mid-sentence[^tip] like this.

[^1]: The original spec was written by John Gruber.
[^docs]: GitHub, Reddit, and Stack Overflow all use it.
[^tip]: Labels can be words, not just numbers.

2. Embedding Raw HTML

Markdown can't do everything — there's no syntax for centring text or colouring a word. When you hit that wall, you can drop raw HTML straight into your Markdown and most renderers (GitHub included) will honour it. Common uses: <p align="center"> to centre a logo, <kbd> to style keyboard keys, <br> for a manual line break, and <span style="..."> for inline colour.

Markdown is great, but sometimes you need raw HTML.

<p align="center">
  <strong>Centred text</strong> — Markdown alone can't do this.
</p>

This text is <span style="color: tomato">tomato-coloured</span>
and this is <kbd>Ctrl</kbd> + <kbd>C</kbd> in a keyboard tag.

<br>

A manual line break above using the <br> tag.

3. Escaping Special Characters

Characters like *, _, #, and ` have special meaning in Markdown. To show them literally instead of triggering formatting, put a backslash \ in front. So \*hello\* displays the asterisks instead of turning the word italic. This is the difference between escaping (show the symbol) and literal (the symbol already would have shown) — you only need a backslash when the character would otherwise be interpreted.

Show literal Markdown by escaping with a backslash \\ :

\\*not italic\\*   ->  *not italic*   (the asterisks stay visible)
\\# not a heading -> # not a heading
\\` not code \\`  ->  ` not code `
1\\. not a list   ->  1. not a list

Characters you can escape: \\ \` * _ {} [] () # + - . ! |

4. Collapsible Sections

A collapsible section hides content behind a clickable label — perfect for long FAQs, solutions, or stack traces. It's raw HTML: wrap the content in <details>, and put the always-visible label in <summary>. The one rule that trips everyone up: leave a blank line after </summary> if you want Markdown (lists, code, bold) to render inside.

## Troubleshooting

<details>
<summary>Why won't my footnote render?</summary>

The label after `[^` must match **exactly** between the
reference and the definition. `[^1]` needs `[^1]:` — not `[^one]:`.

You can use **Markdown** inside a collapsed section, including
lists and `code`.

</details>

// 🎯 YOUR TURN — build a collapsible FAQ section.
// Fill in each ___ then press "Try it Yourself" to print your Markdown.

const summaryText = "___";   // 👉 the always-visible label, e.g. "Show the answer"
const hiddenText  = "___";   // 👉 the text revealed when expanded

console.log("<details>");
console.log("<summary>" + summaryText + "</summary>");
console.log("");                       // blank line is REQUIRED for Markdown inside
console.log(hiddenText);
console.log("");
console.log("</
...

5. A Table of Contents with Anchor Links

Every heading on GitHub automatically gets an invisible anchor (a link target). You can link to it with [Text](#heading). To work out the anchor: take the heading text, make it lowercase, replace spaces with hyphens, and drop punctuation. So ## FAQ & Support becomes #faq--support (the & is dropped, leaving a double hyphen where the spaces were). String these links into a bullet list and you have a clickable table of contents.

# Project Handbook

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [FAQ & Support](#faq--support)

## Installation
...

## Usage
...

## FAQ & Support
...

6. Badges (shields.io)

Those little status pills at the top of READMEs — build passing, MIT license, version 2.1.0 — are just images. shields.io generates them from a URL, and you embed each one with normal image syntax ![alt](url). The static pattern is .../badge/LABEL-MESSAGE-COLOR.

# Awesome Project

![Build](https://img.shields.io/badge/build-passing-brightgreen)
![Version](https://img.shields.io/badge/version-2.1.0-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![PRs](https://img.shields.io/badge/PRs-welcome-orange)

Pattern: https://img.shields.io/badge/LABEL-MESSAGE-COLOR

7. Syntax Highlighting & Emoji

A fenced code block (three backticks) becomes syntax-highlighted when you write the language name right after the opening backticks — python, json, bash, diff, and dozens more. And emoji shortcodes like :tada: render as 🎉 — handy for friendly headings and changelogs.

Tell the fence its language for syntax highlighting:

\`\`\`python
def greet(name):
    return f"Hello, {name}!"
\`\`\`

\`\`\`json
{ "name": "ada", "active": true }
\`\`\`

\`\`\`diff
+ added this line
- removed this line
\`\`\`

def greet(name):
    return f"Hello, {name}!"

{ "name": "ada", "active": true }

+ added this line
- removed this line

Here's a worked example that prints real GFM source you can copy. Run it, read each printed line, then paste it into a GitHub README to watch it render.

// This program PRINTS GitHub-Flavoured Markdown source so you can
// copy it into a README. The console shows the SOURCE; GitHub shows
// the RENDERED result (checkboxes, footnote links, emoji).

console.log("=== Task lists (recap) ===");
console.log("- [x] Create repository");   // renders as a ticked box
console.log("- [ ] Write the README");    // renders as an empty box
console.log("");

console.log("=== Footnotes ===");
console.log("Markdown is everywhere[^1].");
console.log("[^1]: Used by
...

// 🎯 YOUR TURN — add a footnote. The label in the REFERENCE must match
// the label in the DEFINITION exactly, or GitHub won't link them.

const label = "___";   // 👉 pick a label WITHOUT the ^, e.g. note  (used as [^note])
const note  = "___";   // 👉 the footnote text shown at the bottom of the page

console.log("Markdown supports footnotes[^" + label + "].");
console.log("");
console.log("[^" + label + "]: " + note);

// ✅ Expected printed source (example, label = "note"):
//    Markdown su
...

One more runnable tour that prints the source for an anchor-link TOC, escaping, raw HTML, and a highlighted fence — all in one place.

// Quick tour of advanced GFM extras (printed as source).

console.log("=== Anchor-link Table of Contents ===");
console.log("- [Setup](#setup)        // jumps to the '## Setup' heading");
console.log("- [FAQ & Help](#faq--help)// spaces->-, '&' dropped, lowercased");
console.log("");

console.log("=== Escaping special characters ===");
console.log("Type a literal asterisk: \\*not italic\\*");
console.log("Type a literal hash:     \\# not a heading");
console.log("");

console.log("=== Raw HTML 
...

// 🎯 MINI-CHALLENGE: print a mini README section
// Build (with console.log) the SOURCE for a small README that includes:
//   1. An H1 title line:           # My Tool
//   2. ONE shields.io badge:       ![License](https://img.shields.io/badge/license-MIT-green)
//   3. A collapsible "Install" section using <details>/<summary>
//   4. A fenced \`\`\`bash code block with one install command
//
// ✅ Expected printed source (shape):
//    # My Tool
//    ![License](https://img.shields.io/badge/lic
...