So you want a website that does not require a server that cries itself to sleep each night. Good call. GitHub Pages hosts static sites with minimal fuss and maximum smugness. This guide walks you through the parts that matter while keeping the fake ceremony to a minimum.

Create the repository

Start on GitHub and make a new repository. If you want a user or organization site the repo name must match username.github.io exactly. For project sites pick any name and expect a URL under your username domain. Add your files directly on GitHub or clone locally and use your normal Git workflow.

Local workflow that actually works

git init
git add .
git commit -m "Initial site"
git branch -M main
git remote add origin git@github.com:username/repo.git
git push -u origin main

Choose the publishing source

Open the repository settings and enable GitHub Pages. Pick the branch and folder to publish from such as main and root or use a gh-pages branch. That chosen branch becomes the source for the live site. No wizardry required, just pick the thing you actually want to maintain.

Pick a theme or use Jekyll

If you want instant design gratification try the Pages theme chooser. If you prefer templating and content in markdown use Jekyll. Jekyll supports layouts, includes, and a small set of plugins allowed by GitHub Pages. A simple _config.yml controls site title, baseurl, and other basics.

Simple Jekyll folder layout

• index.html or index.md at the site root
• _layouts for templates
• _posts if you intend to blog

Custom domain and HTTPS

Want a domain that sounds like you own the internet even if you do not? Add a CNAME file to the repository with your domain or set the proper DNS records at your registrar. After DNS changes give it some time while GitHub provisions HTTPS for the domain. The Pages dashboard reports status and DNS warnings so you do not have to guess in the dark.

Deployments and edits

Make small edits, commit, and push. Each push triggers a deployment from the selected publishing source and the site updates. If the page does not show changes check the Pages build log and the repository actions or console output for clues.

Troubleshooting tips that save dignity

• If your user site is not at username.github.io double check the repo name and branch
• If assets 404 check that the baseurl and file paths are correct in _config.yml or HTML
• If HTTPS is not ready wait for DNS propagation and check the Pages dashboard for warnings
• If builds fail read the Pages or Actions log for error messages and missing dependencies

That covers repository creation, content placement, publishing source selection, theme or Jekyll setup, custom domain configuration, and how to push updates. You now have a static site hosted on GitHub Pages ready to take on the internet with very little drama. Go forth and deploy something small and proud.