The moment
Everything so far happened in a browser tab only you could see. Today that changes. Your page - headings, photo, table, badges, Mermaid diagram, all of it - goes live at a real public URL. This is the shortest concept block of the course on purpose: today is for shipping, not studying.
GitHub in 5 minutes, no trauma 5 min live
You do not need to be a programmer to use GitHub, and today you will not touch a terminal or type a single git command. Two ideas and three buttons are the whole toolkit.
LiveWhat GitHub is, for a non-coder2 min▶
Strip away the developer mystique and GitHub is a place that stores text files and renders markdown beautifully. That's genuinely all you need it to be today. Two words of vocabulary:
- Repo (repository): a folder with a name. Yours will hold exactly one file.
- Commit: a save, with a short note attached saying what changed. That's it - "commit" is developer for "save with a memo".
Your markdown file needs zero changes to work there. GitHub speaks GFM - the exact flavor you've been writing since Session 2.
LiveThe web editor: three buttons, no terminal2 min▶
Everything today happens on github.com in your browser:
- The pencil ✏️ on any file opens it for editing, right on the page.
- The Preview tab shows the rendered result before you save - GitHub's version of your split-pane right side, one click away.
- The Commit button saves, with your note. The moment you commit, the change is live.
Edit, preview, commit. That loop is the entire workflow, and you'll run it three times before this session ends.
Self-studyWhat version history buys you2 min read▶
Every commit is kept, forever. Click History on any file and you can see every version you ever saved, who saved it, and when. Nothing is ever overwritten - which means fearless editing: you cannot destroy your page, only add versions of it. Made a mess? Open History, view the last good version, copy it back, commit again.
This is why the world's documentation lives on GitHub: the entire Python docs, Microsoft's docs, most open-source READMEs. Thousands of strangers edit the same markdown files, and version history means no edit is ever a risk. The safety net you get on your one-file profile repo is the same one protecting projects with a million users.
The magic repo 4 min live
GitHub has one special trick: create a repo named exactly your username, and its README takes over the top of your public profile page. GitHub's docs call it a "special repository" - we call it the magic repo. Four conditions, all required.
LiveThe username/username trick: ALL FOUR requirements2 min · recite these▶
Straight from GitHub's docs - your profile README shows only when all four hold:
- 1 · Name match: the repository's name matches your GitHub username exactly. Username octocat needs repo octocat/octocat.
- 2 · Public: the repository is public.
- 3 · Right file, right place: a file named README.md sits in the root of the repository.
- 4 · Not empty: the README.md contains any content at all.
Miss any one and the profile simply shows nothing - no error, no hint. Memorize the four and you can debug any invisible profile in a minute.
LiveThe creation flow, in one breath1 min▶
New repository → name it your username → Public → check "Add a README file" → Create.
Two nice surprises when the name matches: GitHub shows a banner telling you that you've found the special repository, and the "Add a README file" checkbox pre-populates the README with a starter template. You'll see both live in Demo 1 - and then replace the template with three sessions of your own work.
Self-studyHow a profile README can vanish2 min read▶
The four requirements also read as a troubleshooting list. GitHub hides or removes your profile README when:
- The file is empty - content deleted, even accidentally, and the section disappears.
- The repo goes private - flip the visibility and the profile goes blank until you flip it back.
- The names stop matching - rename your account or the repo without renaming the other, and the magic breaks silently.
Legacy quirk: if a matching repo was created before July 2020 (before this feature launched), it won't show automatically - there's a manual "Share to profile" step in the repo settings. You won't hit this with a fresh repo; you might when helping a colleague with an old account.
Where markdown takes you next 3 min live
Today closes the course, not your markdown career. A quick honest map of the territory: what transfers everywhere, and where you'll use it next week without noticing.
LiveThe flavors reality: what you learned travels1.5 min▶
Every app implements markdown slightly differently - the variants are called flavors. The honest picture:
- CommonMark core (Session 1's elements) works everywhere, full stop.
- GFM (tables, checklists, emoji, Mermaid - Sessions 2-3) works on GitHub and most modern tools.
- Every app has quirks at the edges - when something fancy fails, suspect the flavor before you suspect yourself.
Rule of thumb: what you learned in this course maps roughly 95% everywhere. The remaining 5% is a quick check of the app's docs, and the deep-dive flavor map (DD2) if you want the whole landscape.
LiveYour new superpowers map1.5 min▶
- Notes: Obsidian and Notion are markdown underneath - your notes just became portable and future-proof.
- Docs at work: team wikis, project READMEs, internal docs - most of it is markdown, and you now write it natively.
- AI chats: your prompts and the AI's answers ARE markdown. Structure a prompt with headings and lists and the model follows your structure; read an answer's raw markdown and you see exactly how it organized its thinking. The deep dive on this is DD1: Markdown for AI work.
A project manager from an earlier cohort started writing status updates as markdown checklists in the team Slack. Same content as before - but scannable. Within a month the whole team had copied the format, and her "how do you make those" answer was this course. Markdown spreads because reading it sells it.
Self-studyEditors, publishing paths, and GitHub's social syntax3 min read▶
- Editors tour: StackEdit and Dillinger you know (browser, free). Next steps: iA Writer for beautiful focused writing, VS Code with its built-in markdown preview if you drift toward code.
- Publishing paths (teaser): markdown files can become entire websites - GitHub Pages hosts them free, Jekyll and MkDocs turn folders of .md into blogs and documentation sites. That's the DD2 rabbit hole.
- GitHub's social syntax: in issues and discussions, @username notifies a person and #123 auto-links to issue number 123. Not needed for your profile page - very needed the first time you collaborate.
The shipping pipeline 1 min live
Four stops between your draft and the internet. This is the whole lab - look how short the distance is.
Create the magic repo ★ 8 min · everyone creates
Sign in at github.com and note your exact username - it's in the top-right avatar menu and in your profile URL. You're about to type it as a repo name, and requirement 1 says exactly.
Click the + in the top bar → New repository. In "Repository name", type your username. Watch for the banner: GitHub tells you that you've found the special repository. That's the confirmation the magic is on.
Make sure Public is selected (requirement 2) and check "Add a README file" (requirements 3 and 4 in one checkbox - the file exists, in the root, with starter content).
Click Create repository. You land in your new repo with a pre-populated README already rendering. Now open your profile page in a new tab - github.com/yourusername - and there it is, the template, live on your profile. All four requirements: met.
The ship ★ 12 min · this is the moment
In your new repo, click README.md, then the pencil ✏️ to edit. Select all the template content and delete it - it did its job; your page is better.
Switch to your StackEdit tab, select your whole about-me page, copy. Back in GitHub: paste. Three sessions of work, one paste.
Click the Preview tab. This is the Session 3 trust-the-syntax payoff: the badges and the Mermaid diagram that stayed raw in StackEdit render right here. Scroll the whole page. Check the photo, the table, the collapsible section.
Anything off? Flip back to the editing tab, fix it, preview again. This edit-preview loop is exactly your split-pane editor with one extra click.
Happy? Click Commit changes, write the message my page, v1, and commit. Now open your profile tab and refresh. IT'S LIVE.
📱 Phone-out moment: take out your phone, open github.com/yourusername in the browser, and show your neighbor. That page renders on every device on Earth right now, and you wrote it in plain text.
The victory lap ★ 5 min · feel how cheap edits are
One more edit, right now: pencil, add a line at the bottom of your page - *built in learn-markdown-with-phoebe* or today's date - and commit with the message v1.1. Refresh your profile. Total time: under a minute. That's how cheap edits are now. Your page is never finished, only current.
Browse time: open the profiles of two classmates (swap usernames with your neighbors). See what they did differently - a badge you didn't think of, a better table, a funnier bio.
Leave verbal compliments - one thing you genuinely liked on each page, said out loud. You've all just shipped something public. That deserves noise.
This week and beyond ◐ ongoing
- Share your link somewhere real: a LinkedIn post, your team chat, your email signature. "I built my GitHub profile page from scratch this month" is a legitimately good post - and the page backs it up.
- Start a 30-day tweak streak: one tiny commit a week - reword a line, add a badge, update the checklist. Four commits from now, editing your public page will feel as casual as editing a note.
- Explore the deep-dive track when curiosity strikes: DD1 · Markdown for AI work, DD2 · Flavors and export, DD3 · Mermaid beyond basics.
- Steal like a profile artist: search GitHub for "awesome profile readme" collections, star one repo of examples, and borrow one idea for your next tweak.
Three questions before you celebrate 🎯 ◐ 90 seconds
1 · Your repo is named exactly your username, it's public, and README.md sits in the root - but your profile shows nothing. Which requirement did you miss?
Four requirements, all required: exact name match, public, README.md in the root, and any content in it. No stars, no settings toggle - if three hold and nothing shows, the file is empty.
2 · You set the username/username repo to private "just while I polish it". What happens to your profile?
Public is requirement 2, and it's binary: private repo, blank profile - silently, with no notice shown. Polish in the Preview tab instead; it's private until you commit.
3 · You've pasted your page into the GitHub editor. Where do you verify the rendering - Mermaid, badges, all of it - BEFORE it goes public?
The Preview tab renders full GFM - Mermaid and badges included - while your changes are still private. Preview, fix, then commit: the pro loop.
Official sources covered
This session teaches the working content of GitHub's official docs on managing your profile README plus the tools-and-flavors half of Markdown Guide's getting started.