Where your page stands
After two sessions your about-me page has headings, lists, links, a photo, a quote, a skills table, and a checklist. Solid - but it still looks like homework. Today's session is pure polish: the small touches that make strangers on GitHub think "this person knows what they're doing." Next week it goes live, so this is dress rehearsal.
Badges and emoji 5 min live
The two fastest polish wins. One is a clever reuse of syntax you already know; the other is typing : and letting GitHub do the rest.
LiveBadges: Session 2's image syntax, pointed somewhere clever2.5 min▶
- a crisp two-tone pill, like the pro READMEs
- Anatomy of the URL: img.shields.io/badge/LABEL-MESSAGE-COLOR - left text, right text, right-side color, separated by hyphens. Spaces become %20.
- Honesty beat: badges are NOT markdown and NOT a GitHub feature. They're a community convention powered by shields.io, a free service that generates badge images on demand. You're just using Session 2's  image syntax - pointed at a machine that draws pills.
- Which means: they render anywhere images render - including stackedit. No new rules to learn, and one pattern covers endless badges. The full parameter zoo lives at shields.io.
Open any famous repo - React, VS Code, pandas - and the first thing under the title is a badge row: build passing, version, license, downloads. Those are all shields.io-style images. Your "Made with Markdown" badge uses the exact same mechanism as a badge with 20 million weekly viewers.
LiveEmoji: shortcodes on GitHub, paste anywhere2 min▶
Learning markdown 👍 and shipping soon 🚀
- Shortcodes: :name: between colons - :+1:, :rocket:, :coffee:. On GitHub, typing : pops up an autocomplete list - browse it, you'll find everything.
- The universal alternative: copy-paste the emoji character itself (🚀) straight into your text. It's just a character - works in ANY markdown app, no rendering required.
- Dose carefully: emoji are seasoning, not soup. A few as section markers or personality accents reads friendly; one per word reads like a ransom note.
Self-studyWhere shortcodes fail + highlight + sub/superscript2 min read▶
- Shortcodes vary by app: :joy: renders on GitHub and Slack but may sit there as literal text elsewhere - each app keeps its own shortcode list. When in doubt, paste the real emoji character instead.
- Highlight: ==important== marks text with a highlighter effect - but only in SOME processors (not GitHub). Check before relying on it.
- Sub and superscript: markdown has no native syntax, so borrow HTML - H<sub>2</sub>O and x<sup>2</sup> both work on GitHub, as does underline via <ins>.
Diagrams from text - Mermaid 5 min live
The wow moment of the course: type a few lines of text, get a real flowchart. No drawing tool, no dragging boxes - and the diagram lives in your file like everything else.
LiveThe mermaid fence: a code block that draws2.5 min▶
a rendered flowchart - real boxes, real arrows
- It's Session 2's code fence with mermaid as the language id. GitHub sees that word and, instead of showing code, hands the text to the Mermaid engine and displays the drawing. This exact example is straight from GitHub's own docs.
- Reading the lines: graph TD; declares a flowchart, then each A-->B; line means "draw an arrow from node A to node B." Name the nodes, state the arrows, done.
- StackEdit reality check: Mermaid may not render in your split-pane editor - it's a GitHub (and mermaid-aware apps) feature. Trust the syntax; github.com's preview tab is the ground truth.
LiveNode shapes and flow direction2 min▶
- Label a node by putting text in brackets after its id - the bracket style picks the shape: A[step] draws a rectangle, A(step) a rounded box, A{choice?} a decision diamond.
- Direction: graph TD flows top-down; graph LR flows left to right - usually the better fit for timeline-ish stories like your learning journey.
- That's genuinely enough to diagram most ideas. Sequence diagrams, pie charts, and gantt charts exist too - the deep-dive track (DD3) and mermaid.js.org have the full tour.
Self-studyWhat GitHub renders + version check + plugin warning2 min read▶
- Four diagram fences render on GitHub: mermaid, geojson, topojson (maps), and stl (3D models). We teach mermaid; the others exist if you ever need a map or a 3D part.
- Which Mermaid version is GitHub running? Put the single word info inside a mermaid fence - the rendered block reports the version.
- Plugin warning: GitHub's docs caution that third-party Mermaid browser extensions can conflict with the built-in rendering. If a diagram misbehaves, try a browser profile without extensions before blaming your syntax.
The traps: what works where 2 min live
Polish features are the least portable markdown you'll write. Two minutes now saves a confused ship day.
LiveThe color-chip trap + alerts, in moderation2 min▶
- The color-chip trap: writing a hex code in backticks like `#083FA1` renders a cute color swatch next to it - but ONLY in issues, pull requests, and discussions. In a README it's just monospace text. Don't design your profile page around a feature that won't be there.
- Alerts: > [!NOTE] on its own line turns the blockquote under it into a styled callout box. Five types: NOTE, TIP, IMPORTANT, WARNING, CAUTION. These DO work in READMEs - but they're GitHub-flavored, so other apps show a plain quote.
- Dosage: GitHub's own guidance - use alerts sparingly, one or two per document, and don't nest them. An alert that's everywhere alerts no one.
Build your badge row ★ 7 min · everyone types
Open your about-me draft (stackedit tab or github.com editor). Go to the very top, directly under your # Name heading, and add a blank line for the badge row.
Type your first badge: . Badges are images, so stackedit renders them live - watch the pill appear.
Add two more on the same line, one space apart. Make them YOU - playful beats corporate: Currently%20learning-markdown-orange, Coffee%20level-critical-red, whatever's true.
Read the pattern back out loud: LABEL, hyphen, MESSAGE, hyphen, COLOR, spaces as %20. That's the whole grammar - you can now mint badges forever.
Fold, sprinkle, navigate ★ 8 min · everyone builds
Add a collapsible: type <details>, then <summary>More about me</summary>, a BLANK line, two or three fun facts as a list, then </details>. The blank line after the summary is the step people miss.
Emoji sprinkle: add 3 to 5 emoji where they earn their place - one next to a section heading, one in your intro line, one in the fun facts. Shortcodes like :rocket: are GitHub's dialect; if your editor shows literal text, paste the real emoji character or trust the syntax.
Now the mini TOC: under your badge row, add ## Contents and a bulleted list of three section links - [About me](#about-me) style. Lowercase, spaces to hyphens.
Taste check: collapse your eyes half-shut and look at the page. 3-5 emoji reads warm; 50 reads chaotic. Cut until it feels like you on a good day.
Draw your journey in Mermaid ★ 7 min · everyone types
Near the bottom of your page, add a ## My journey heading, then open a fence: three backticks plus mermaid on the same line.
First line inside: graph LR; - your story flows left to right.
Tell it in 4 or 5 nodes: A[Curious about markdown]-->B[This course]; then B-->C[Markdown fluent];. Add one branch - maybe B-->D{Ship my page?}; and D-->C;. Close with three backticks.
Preview: got a GitHub account? Paste your page into a new file on github.com and click the Preview tab - the diagram renders there, ground truth. No account yet? Trust the syntax today; next week's session starts by making the account and you'll see it render live.
This week ◐ 30 min total
- Finish the polish items you didn't get to in the lab: badge row, collapsible, mini TOC, journey diagram. Your page should feel done, not draft.
- Pick your final structure for ship day: which sections stay, what order, what folds into a collapsible. Ship day is assembly, not authorship.
- Create a free GitHub account if you don't have one - github.com/signup, two minutes. This one is REQUIRED: Session 4 is publish day and there is no publishing without it.
- Optional playground: mermaid.live renders Mermaid as you type - the stackedit of diagrams. Ten minutes there and flowcharts become a reflex.
Three questions before you go 🎯 ◐ 90 seconds
1 · What IS a badge, really?
No new markdown involved - it's Session 2's  aimed at a badge-generating service. A community convention, not a markdown or GitHub feature.
2 · You put `#083FA1` in your README expecting a color swatch. What renders?
The color-chip trap: the swatch is an issues/PRs/discussions feature. READMEs show plain inline code. Lane 3 on the decision map.
3 · How do you tell GitHub "this block is a diagram, not code"?
Same fence you learned in Session 2 - the language word mermaid tells GitHub to render a drawing instead of highlighting code.
Official sources covered
This session teaches the polish layer from GitHub Docs writing syntax, GitHub Docs on creating diagrams, and the mermaid.js.org introduction - plus one honest community convention.