How this site works

Six files in a Git repository, 239 KB in total. GitHub copies them onto its web servers and hands them to anyone who asks. None of my code runs on the server.

The repository name is the address

GitHub publishes a repository named aarora79.github.io at https://aarora79.github.io/. The name does the work. Nothing else configures it, and renaming the repository moves the address.

Every other repository publishes under a path instead. my-reading-list serves at aarora79.github.io/my-reading-list/. You get one root site per account, plus a path for each repository where you switch Pages on.

Files map to URLs

The repository is the file tree the web server sees. A request for a directory returns the index.html inside it. That is the whole rule.

File in the repo	Address it answers
`index.html`	`/`
`explainers/jev/index.html`	`/explainers/jev/`
`explainers/jev/poster/index.html`	`/explainers/jev/poster/`
`notes.html`	`/notes.html`

A folder with an index.html gives the cleaner address, so I use that shape and skip the .html on the end.

Pushing is deploying

git push ships the site. GitHub sees the new commit on main, copies the files out, and serves them. The first push went live in about fifteen seconds.

The HTML I commit is the HTML the browser receives, byte for byte. Nothing rewrites it on the way through.

The two odd files

.nojekyll is empty, and its presence alone tells GitHub to skip Jekyll. Jekyll is a blog generator that Pages runs by default, and it ignores any file or folder whose name starts with an underscore. Plain HTML needs none of it.

404.html answers any address matching no file. GitHub picked it up on the first push.

What it cannot do

No code of mine runs on the server, which rules out reading a database, checking a password, handling a form submission, hiding an API key, and anything that changes per visitor. Every visitor gets identical bytes.

JavaScript inside a page still runs, in the visitor's browser. A page can call a public API, draw a chart, or filter a list. The JEV poster lays out two A4 pages with inline CSS and base64 images, and asks the server for nothing.

Adding a page

mkdir -p explainers/new-thing
cp ~/somewhere/thing.html explainers/new-thing/index.html
git add -A && git commit -m "Add new thing" && git push

It answers at /explainers/new-thing/ within a minute. Add a card on the homepage so people can find it.

A self-contained file drops straight in. One that points at style.css or img/photo.png needs those files copied alongside it, at the same relative paths, or the page loads with no styling.

When a change does not appear

Open the repository's Actions tab. Every push runs "pages build and deployment", and a red mark means the files never shipped.
Green run, stale page: the browser cached it. Hard reload.
Check that Settings → Pages still reads main and /.

Limits

1 GB for the published site, 100 MB for any single file, and roughly 100 GB of traffic a month. This site uses 239 KB, so the ceiling is about four thousand times the current size.

If I ever buy a domain

The hosting stays free. A registrar charges for the name, about $10 to $15 a year for a .com. Point DNS at GitHub, type the domain into Settings → Pages, and GitHub issues a certificate and serves HTTPS.

For a subdomain like blog.example.com, that is one CNAME record aimed at aarora79.github.io. For a bare example.com, it is four A records: 185.199.108.153 through 185.199.111.153.

One catch worth knowing first: a custom domain on this repository takes the path sites with it, so my-reading-list would start answering at example.com/my-reading-list/.