Push to main. Site goes live in 60 seconds. No build step, no Netlify, no Vercel, no DNS, no server. Just a static folder named /docs or a branch called gh-pages and a one-click toggle in repo settings.
GitHub Pages is a static-file CDN attached to a public repo. There's no runtime, no server-side code, no database. The whole service is "we'll serve whatever's in this folder over HTTPS with a green lock and a free cert." That's the whole product.
index.html plus an assets/ dir.<username>.github.io/<repo>/. Custom domains work — point an A record at GitHub's four IPs (185.199.108.153, .154, .155, .156) or a CNAME at <username>.github.io.certbot, no cron. Add a custom domain and the cert shows up within minutes.If your content is a doc, a portfolio, a landing page, a marketing site, a research notebook, or a blog with no comments — Pages is the right tool. It's not the right tool for SPAs that need server-side routing, dashboards with auth, or anything that needs a database.
| What you want | Pages? | Why |
|---|---|---|
| Doc / long-read / portfolio | yes | Static files, low traffic, free hosting, free CDN. |
| Marketing / landing page | yes | Same. Pages is designed for this shape. |
| Personal blog (no comments) | yes | Markdown → static HTML via a build step on push, or just commit HTML. |
| Project hub with multiple sections | yes | Each section gets its own folder and index.html. That is this site. |
| Web app with user accounts | no | You need server-side auth. Pages can't run it. |
| SPA with client-side routing | mixed | Pages serves the SPA shell fine, but 404s on deep links. Add a 404.html that redirects, or use HashRouter. |
| Anything with a database | no | Pages has no runtime. Use Render, Fly, Railway, or a managed DB + Pages frontend. |
Push a single HTML file. Open Settings → Pages. Pick the branch. Wait 60 seconds. Your site is live on the public internet with HTTPS. That's the whole flow. If your stack needs more than that to go from "files on disk" to "live URL," your stack has too much ceremony.
The page you're reading right now is a single static HTML file. The whole kai-systems hub is 9 such files plus one shared CSS. The "build" is a typo for "git commit." Here's the actual layout on disk:
No package.json in the runtime path. No node_modules. No bundler. The CSS lives in one file. Each page has its own inline <style> for the hero and the section layouts, but everything inherited (tokens, body base, nav strip, fonts) comes from assets/shared.css.
From an empty GitHub account to a live site. The full ceremony, top to bottom, with the exact commands and the exact screens.
kai-systems lives at /kai-systems/.git push.CNAME at the repo root containing your domain (one line, no protocol). At your DNS provider, add either four A records pointing to GitHub's IPs or one CNAME pointing to kajica2.github.io. The cert shows up within 15 minutes.After the first deploy, every site-level setting (custom domain, HTTPS enforcement, custom 404, build branch) lives at Settings → Pages. Everything repo-level (visibility, collaborators, branches, Actions permissions) is in the same Settings page but other tabs. The split is intentional: Pages settings are about serving, repo settings are about the source.
Three forks that make sense, ordered from smallest to largest. Pick the shape that matches what you're actually shipping.
index.html with inline styles. No assets/ dir at all. Pages serves it directly. The whole site is one URL./src are markdown. A GitHub Action runs a static site generator (Jekyll is built-in, or Hugo / Eleventy via community actions) and pushes the rendered HTML to main or gh-pages. Pages serves the output, not the source.For most projects, serve from main and commit rendered output directly. If you have a heavy build that runs on every push, serve from a separate gh-pages branch — the source stays on main, the build action pushes artifacts to gh-pages, and Pages only watches the artifacts branch. This is how Jekyll-powered GitHub Pages works by default and it keeps the build noise out of the source history.
If you need server-side rendering for SEO of dynamic routes, or you need auth, or you need a database, or you need server-side form handlers — Pages is the wrong tool. Don't fight it. Use Vercel or Render for Next.js, Fly or Railway for full-stack Node/Python, or Cloudflare Pages for serverless functions. Each of those is also free-tier and one-click deploy. Pages is for files. Use the right tool.
Nine stacks. One philosophy. Zero babysitting.