user-site-template — HTML Portfolio Template

SHA-256: ad4a96b6aae583e96fc6eb55837119f4892195ba2355d69245cc9dc7c9664a56

2026-10-08T02:38:16.930Z

# user site template

A template for a personal website at `yourusername.github.io` — hand-written static HTML and CSS,
no build step, no dependencies, no JavaScript framework, no tracking. Free to host on GitHub Pages.

It ships as a **complete working demo site**. You get something live and good-looking first, then
Claude Code interviews you and turns it into yours. If you'd rather do it by hand, you can — see
[the manual path](#the-manual-path-without-claude) at the bottom.

**What's included:** a home page (projects, writing, releases, gallery, and links sections), plus
contact, privacy, writing, now, uses, resume, and 404 pages. You keep the ones you want.

**A real site built this way:** [andrewralon.github.io](https://andrewralon.github.io) — the site
this template was extracted from.

---

## Step 1 — create your repo from this template

Click **Use this template → Create a new repository**, then:

- **Repository name must be exactly `yourusername.github.io`**, using your real GitHub username.
- **Visibility must be Public** (GitHub Pages needs this on free accounts).

> ### ⚠️ The name is the one thing you can't get wrong
>
> `yourusername.github.io` is the only name that produces a **user site**, served at the root of
> your domain. Any other name produces a **project site** at `yourusername.github.io/reponame/`,
> where every link in this template — `/style.css`, `/favicon.svg`, `/contact` — silently breaks.
>
> Your username, exactly, then `.github.io`. Nothing else. If you already got this wrong, rename
> the repo in Settings before going further; it's painless now and annoying later.

## Step 2 — keep your email out of your commits

Do this **before your first commit**. Every git commit permanently embeds the author's email
address, and in a public repo that address is visible to anyone — and to every scraper that walks
GitHub. Rewriting history afterwards does not reliably erase it.

1. Go to **[Settings → Emails](https://github.com/settings/emails)**.
2. Tick **Keep my email addresses private**. GitHub shows you a no-reply alias that looks like
   `[email protected]` — copy it.
3. Also tick **Block command line pushes that expose my email**. That's the setting that protects
   you from here on, in every repo.

Claude checks this in Step 4 and offers to configure it for you, so you can skip ahead if you'd
rather. To do it yourself after cloning:

```bash
git config user.email '[email protected]'
```

No `--global` — that sets it for this repo only, leaving your other repos alone.

## Step 3 — clone it

```bash
git clone https://github.com/yourusername/yourusername.github.io.git
cd yourusername.github.io
```

## Step 4 — let Claude set it up

Open [Claude Code](https://claude.com/claude-code) in that folder and run:

```
/setup-site
```

Claude walks the whole thing, in this order:

1. **Checks your setup** — that the repo is named correctly and your commit email is private.
2. **Turns on GitHub Pages** and confirms your site is live. *You'll have a working URL here,
   before answering a single question about content.*
3. **Reads your public GitHub profile and repos** and drafts your projects section from your real
   work — names, descriptions, and languages already filled in.
4. **Asks you a few questions** — your name, your tagline, which sections and pages you want.
5. **Builds and verifies**, then commits and pushes.
6. **Cleans up after itself** — the setup files delete themselves, and you're left with a repo
   that looks hand-built, plus a `CLAUDE.md` that documents how to add to it later.

Expect around ten minutes.

### What Claude won't ask you for

The interview asks for a display name and a tagline. That's it. It never asks for your email,
phone number, address, employer, or location, and it doesn't read those fields off your GitHub
profile even though the API returns them. A personal site is a permanently public, heavily scraped
document, so the template's default is to publish as little about you as possible — the contact
form exists precisely so you never have to put an email address on the page.

Your display name can be your GitHub handle. Plenty of good personal sites are pseudonymous.

---

## Afterwards

Your site is live at `https://yourusername.github.io`. Push to `main` and changes appear in about
30 seconds — there's no CI and no build step, so **the commit is the deploy**.

To preview locally before pushing:

```bash
cd docs && python3 -m http.server 8000   # then open http://localhost:8000
```

Two slash commands stay behind for later: `/add-item` (add a project, release, or post) and
`/new-page` (add a page, with the footer nav updated everywhere).

## The manual path (without Claude)

Everything works fine by hand:

1. In your new repo, go to **Settings → Pages** and set **Source: Deploy from a branch**,
   **Branch: `main`**, **Folder: `/docs`**. Save. Your site is live in a minute or so.
2. Edit the files in `docs/`. Search for `your name`, `your tagline here`, and `yourusername` and
   replace them everywhere — including inside `<title>` and the `og:` meta tags.
3. Delete the pages and sections you don't want. Homepage sections are wrapped in
   `<!-- section: name -->` … `<!-- /section: name -->` comments so they're easy to find.
4. **Update the footer on every page** so it lists only the pages that still exist. On each page,
   the entry for the page you're on is `<span class="here" aria-current="page">` instead of a link.
   Pages that aren't themselves listed in the footer — `404.html` and individual posts — carry no
   `here` at all.
5. For the contact form, get a free access key at [web3forms.com](https://web3forms.com) and paste
   it into `docs/contact/index.html`. It's a public identifier, not a secret.
6. Recolour the site by editing the nine values in the `:root` block at the top of
   `docs/style.css`. Nothing below that block hardcodes a colour.

`SETUP.md` has the full procedure in detail if you want to follow along, and `template/PATTERNS.md`
documents every markup pattern with copy-pasteable examples.

## Why `docs/` and not the repo root

GitHub Pages is configured to serve from `/docs`. Everything the live site needs lives there;
everything at the repo root is on GitHub but unreachable from the web. That's what keeps
`README.md`, `CLAUDE.md`, and your notes off your public site without any extra configuration —
and it's why `/style.css` resolves correctly: `/` means the Pages source root, which is `docs/`.

## License

[MIT](LICENSE) — use it, change it, no attribution needed.