Week 2 publish and review

Why this matters

Today the site stops being a folder on your laptop and becomes a URL anyone can open. That is a real milestone — six days ago you had never written a tag — and it is also the first time your work is judged by whether someone else can understand it.

Two things ship today: the live site, and a README that lets a stranger run and understand the project without asking you anything. The second one is the part most people skip and the part that makes work usable.

Remotes: a second copy elsewhere

Your repository from Day 13 lives entirely inside profile-site/.git on one disk. A remote is a copy of that repository hosted somewhere else — for us, on GitHub — that you can push your commits to and pull other people's from.

A remote gets a short name. By convention the main one is called origin. Once it is configured, git push sends your local commits to it and git pull brings new ones back.

Two things a remote is not. It is not a backup of your working tree: only committed work is pushed, so uncommitted edits stay on your machine. And it is not automatic — you push deliberately, when you want the shared copy updated.

Static hosting

A static host is a server that does one job: when a browser asks for a file, it sends that file back exactly as stored. No code runs, no database is queried. GitHub Pages is one, and it serves the files straight out of your repository.

That is enough for everything you built this week, because HTML, CSS, and images are just files. It is also why your contact form will not work once deployed: nothing is listening to receive the submission. A static host cannot run server code because there is no server code. That arrives in Week 6; Week 11 covers deploying it.

Two consequences you must design around, both of which you already met:

• Your published site lives at https://username.github.io/profile-site/, not at the root of the domain. A root-relative path like /styles.css resolves to https://username.github.io/styles.css and 404s. Document-relative paths (styles.css, images/board.jpg) are what work — the Day 9 rule, now with consequences.
• The host runs Linux, where filenames are case-sensitive. Board.JPG and board.jpg are two different files there and one file on your Mac. This is the classic "works locally, broken live" bug.

The README

README.md is a Markdown file at the top of the repository. GitHub renders it automatically on the repository's front page, so it is the first thing any visitor reads.

A useful README explains the project's purpose, how to set it up, how to use it, and the important decisions behind it. Those four things, in that order. Everything else is optional.

• Purpose — one or two sentences. What is this and who is it for?
• Setup — the exact steps to run it on a fresh machine, with real commands. Name every tool a step needs.
• Usage — what to do once it is running, and the live URL.
• Decisions — why it is built this way. Why Grid for the cards, why semantic landmarks, what you deliberately left out.

The test is not "does it read nicely." It is: could someone with your skills from a week ago follow it start to finish without asking a question? Unnoticed assumptions are what break READMEs.

Walkthrough: from local repo to public URL

1. Create the remote repository. On github.com, create a new repository named profile-site. Make it public — GitHub Pages on a free account requires that. Do not let GitHub add a README, .gitignore, or licence: you already have commits, and an initialised remote makes the first push awkward.

2. Connect your local repository. In profile-site:

git remote add origin https://github.com/USERNAME/profile-site.git
git remote -v

origin	https://github.com/USERNAME/profile-site.git (fetch)
origin	https://github.com/USERNAME/profile-site.git (push)

3. Push.

git branch -M main
git push -u origin main

git branch -M main renames the current branch to main (harmless if it already is). -u sets origin main as the default target, so later pushes are just git push. The output ends with something like:

To https://github.com/USERNAME/profile-site.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Refresh the repository page. Your files and your full commit history are there.

4. Turn on GitHub Pages. In the repository: Settings → Pages. Under Build and deployment, set Source to "Deploy from a branch", choose branch main and folder / (root), and Save. After a minute or two the page shows your URL:

https://USERNAME.github.io/profile-site/

A 404 in the first minute is normal — the build has not finished. Reload after two minutes.

Your turn

1. Push the repository and enable Pages as above. Confirm the live URL loads.
2. Open the live site and check every link and image. Anything broken here that worked locally is almost certainly a leading / or a capital letter — fix the path, commit, push, and wait for the rebuild.
3. Write README.md at the top of the repository covering the four sections: purpose, setup, usage, decisions. Include the live URL, the npx serve command for running it locally, and at least two real decisions from this week (why semantic landmarks, why Grid for the cards, why box-sizing: border-box).
4. Commit it with a clear message and push. Confirm it renders on the repository front page.
5. Hand the README to the hardest test available: read only your own README, from the top, and do exactly what it says and nothing more. Every place you had to rely on knowledge that is not written down is a missing step. Fix them.
6. Add a line to your README noting that the contact form has no backend yet and why.

Common pitfalls

• No index.html at the published root. Pages serves the branch root, so index.html must sit at the top of the repository, not inside a subfolder — unless you pick the /docs folder option in the Pages settings.
• Root-relative paths. /styles.css works locally with npx serve and breaks on Pages, because your site is served from a subpath. Use styles.css.
• Waiting one second and declaring it broken. The first deploy genuinely takes a minute or two.
• A README written from memory. You know your project too well. Follow your own instructions literally; the gaps show up immediately.
• Committing a token or password to make the push work. Never. Use the credential helper or the GitHub CLI, and remember from Day 13 that history keeps secrets forever.

Verify it yourself

Open today's reference, GitHub Docs' Hello World guide, and compare its workflow to yours.

1. The guide introduces branches and pull requests, which this lesson did not use. Read what a branch is for and write one sentence on when it would have helped you this week.
2. Find GitHub's own guidance on what a README should contain. Which of its recommended sections is missing from yours, and is it worth adding?

Record both in notes/day-14.md. Then close the laptop and look at the week: seven days ago you had never written a tag, and there is now a semantic, accessible, responsive, version-controlled site at a public URL that you can explain line by line. Week 3 makes it move.