Hosting a Static Website on GitHub Pages
Question: How to host a index.html in github pages
- Push your code to a GitHub repo.
- In Settings → Pages → Source: set to
/ (root)
ormain
.
Tips:
- Your index.html must be in root of the repo or
docs/
folder.
Question: How to configure a custom domain (CNAME) for GitHub Pages
- In your GitHub repo, create a file named
CNAME
in the root (or in thepublic/
folder if using Astro). - Add your custom domain (e.g.,
yourdomain.com
) as the only line in theCNAME
file. - Push this file to your repository.
- In GitHub, go to Settings → Pages and set your custom domain.
- Update your DNS provider to point your domain to GitHub Pages (usually with an
A
orCNAME
record).
Question: How to deploy with GitHub Actions (and why use it)
- Use the peaceiris/actions-gh-pages GitHub Action to automate deployment.
- This action builds your site and pushes the output to the
gh-pages
branch automatically on every push. - Advantages:
- No manual deployment steps.
- Ensures your site is always up-to-date with your code.
- Supports custom domains and advanced workflows.
Question: Astro vs Hugo for static sites
- Astro:
- Modern, component-based, supports multiple frameworks (React, Vue, Svelte, etc.).
- Ships zero JavaScript by default for fast performance.
- Great for blogs, documentation, and marketing sites.
- Hugo:
- Go-based, extremely fast builds, uses Markdown and Go templates.
- Large theme ecosystem, great for content-heavy sites.
- Why choose Astro?
- If you want to use modern JS/TS, component-based UI, and minimal client JS, Astro is a great choice.
- Hugo is best for pure Markdown content and ultra-fast builds.
Question: How to set up an Astro project for GitHub Pages
- Install Astro:
npm create astro@latest # or pnpm create astro@latest
- Choose a template and follow the prompts.
- In
astro.config.ts
, set thebase
option if your site is not at the root (e.g.,/your-repo-name/
). - Add a
CNAME
file inpublic/
if using a custom domain. - Add a GitHub Actions workflow (see above) to automate deployment.
- Push your code to GitHub and verify your site at your custom domain or GitHub Pages URL.