From repo to real website, without writing a website
Everything you have built so far - the handbook repo (Session 2), the board (Session 3), the PR flow (Session 4) - was already valuable inside your team. Today it faces the world: GitHub Pages converts your markdown into a website and hosts it for free, forever, at username.github.io/repo-name. This course itself is served exactly that way. The only new skill is knowing which settings page to visit and what "deploy" means when you watch it happen.
What Pages is 4 min live
GitHub Pages is free website hosting built into every repository. The whole activation: Settings → Pages → pick a branch → Save. About a minute later your markdown files are a website at username.github.io/repo-name.
LiveWhat "deploy" means, in office terms2 min▶
- Deploy = convert and publish. When you save the Pages setting (and after every future change), GitHub takes your markdown, turns it into web pages, and pushes them to its servers. It takes about 60 seconds; you can watch the progress in the repo's Actions tab and wait for the green check.
- It re-deploys on every merge. Change a file on main - directly or via a PR - and the site updates itself a minute later. Nobody "uploads the new version"; the repo IS the website.
- The URL is predictable: username.github.io/repo-name. Your repo's address on github.com and your site's address on github.io are two views of the same thing.
Self-studyReading the Actions tab without fear2 min read▶
The Actions tab is where deploys (and other automations - Session 6 territory) show their work. For Pages you only need three readings:
- Yellow dot, spinning: the deploy is running. Sixty-ish seconds; go stretch.
- Green check: published. Reload the live site and your change is there.
- Red X: the build hit a snag - almost always a typo in _config.yml (a missing space after the colon is the classic). Click into the run, read the last few lines, fix the file, and the next commit retries automatically.
That is the entire literacy level you need. Session 6 turns this tab from "where deploys live" into a superpower you can read on any repo.
Making it look good with zero code 5 min live
Out of the box, Pages renders your markdown plainly. One tiny file changes that: _config.yml, two lines, copy-paste provided. It is the ONLY configuration file in this entire course - and it is two lines.
LiveHomepage, links and images - the rules you already know3 min▶
- Your README (or an index.md) becomes the homepage. The front door you wrote in Session 2 is now literally the front page of a website. Same file, bigger audience.
- Relative links just work. A markdown link to onboarding.md becomes a working link between pages on the live site. Link every page from the homepage and visitors can reach everything.
- Images drag-dropped into the editor (Session 2's trick) appear on the site too. No upload manager, no media library - the repo is the media library.
- Themes are swappable: change the theme line, merge, reload. Try cayman, minimal or slate before you settle.
You are looking at one right now. This course, and every learn-X-with-phoebe site, is a markdown repo served by GitHub Pages - same Settings page, same flow you will use in ten minutes. And beyond this room: thousands of documentation sites, team handbooks and personal portfolios you have visited are secretly Pages sites. It is one of the most-used publishing systems on the internet, hiding in a Settings tab.
When Pages is the right tool 4 min live
Pages serves documents beautifully and does nothing else. Knowing the boundary keeps you out of trouble - and makes you sound very sharp in meetings.
LivePerfect for, wrong for, and the privacy check3 min▶
| Perfect for | Wrong tool for |
|---|---|
| Team handbooks and internal docs made public-safe | Web apps with buttons that DO things |
| Portfolios and personal landing pages | Anything with logins or user accounts |
| Course sites (hello!) and documentation | Databases, forms that save data, shops |
| Project one-pagers and event pages | Sites that must be private on the free plan |
The pattern: Pages serves pages - words, images, links. The moment your idea needs to remember visitors or process input, that is real web hosting (and a chat with an engineer).
Self-studyCustom domains + github.io URL anatomy2 min read▶
- Custom domains exist: handbook.yourcompany.com can point at your Pages site - Settings → Pages → Custom domain, plus one record set by whoever manages your company's domain. The official docs walk through it (docs.github.com → Pages → custom domains).
- URL anatomy: username.github.io/repo-name is a project site - every repo can have one. The special repo named exactly username.github.io becomes your profile site, served at the bare username.github.io. One per account; a natural home for a portfolio.
Ship it ★ 10 min · everyone goes live
The moment four sessions built toward. When your URL loads, post it in the room chat - we applaud every single one.
Open your handbook repo → Settings → Pages. Under Build and deployment, set Source to Deploy from a branch, pick main, folder / (root), and press Save.
Go to the Actions tab and watch the deploy run - about 60 seconds until the green check. That was a deploy; you just watched one happen.
Open username.github.io/team-handbook (the link also appears at the top of the Pages settings). Your handbook is on the internet. Post the URL in the room chat - applause moment.
Now fix one thing you immediately hate (there is always one) - but do it the Session 4 way: pencil edit → branch → PR → merge.
Watch Actions redeploy, reload the live site, see your fix. You just used a pull request as a publishing pipeline. That is the whole loop.
Theme it ★ 6 min · everyone styles
In your repo: Add file → Create new file. Name it exactly _config.yml (the underscore matters).
Paste the two lines:
title: Team Handbook
theme: jekyll-theme-cayman
Commit it straight to main this once (it is your repo's outfit, not its content). Wait for the green check in Actions, then reload the live site: header, colors, typography - a whole design, from two lines.
Not your style? Try jekyll-theme-minimal or jekyll-theme-slate - and make THIS change via a branch + PR, watching the site republish when you merge. Feel the publishing pipeline under your fingers.
The go-live checklist ★ 6 min · everyone audits
Before you share that URL beyond this room, audit your own repo honestly. This checklist is reusable for every site you ever ship.
This week ◐ 30 min total
- Polish the live site: at least 3 pages (homepage plus two more), every page linked from the homepage, theme you actually like. Small PRs, watch each one republish.
- Share the URL with one real colleague and ask them to file an issue with feedback (they learned how in your Session 3 world; if not, teach them in two minutes - it is a form).
- Watch the system work as one thing: their issue lands on your Session 3 board, you fix it with a Session 4 PR that says "closes #N", the merge closes the issue AND republishes the Session 5 site. Three sessions, one machine.
Three questions before you go 🎯 ◐ 90 seconds
1 · Your Pages site is live. What makes it update?
The setting is one-time; after that, every change to main republishes in about a minute. Your PR flow IS the publishing pipeline.
2 · On the free plan, who can see your Pages site?
Public even if the repo is private. That is why the privacy row on the go-live checklist is worth triple points.
3 · Which of these is Pages the WRONG tool for?
Logins, forms that save data, databases = a real web application, which needs real hosting. Pages serves pages: words, images, links - and it serves them brilliantly.
Official GitHub Skills coverage
This course maps to GitHub's own free Skills exercises - each session tells you honestly what is covered here and what the official course adds.