GitHub Pages
Host a static website for free straight from a GitHub repository.
GitHub Pages serves static HTML, CSS, and JavaScript directly from a repo, for free. It is perfect for project docs, portfolios, and landing pages.
Enabling Pages
- Go to Settings → Pages.
- Choose a source: a branch (like
main) and folder (/rootor/docs). - Save; your site appears at
https://username.github.io/repo.
You can also build Pages with a GitHub Actions workflow, which is required for many static-site generators.
Example
# Minimal workflow to deploy a static folder to Pages
name: Deploy Pages
on:
push:
branches: [main]
permissions:
pages: write
id-token: write
jobs:
deploy:
runs-on: ubuntu-latest
environment: github-pages
steps:
- uses: actions/checkout@v4
- uses: actions/upload-pages-artifact@v3
with:
path: ./public
- uses: actions/deploy-pages@v4When to use it
- An open-source developer publishes their library's documentation site at username.github.io/my-lib directly from the docs/ folder.
- A student deploys a personal portfolio as a static site on GitHub Pages at username.github.io with zero hosting cost.
- A team auto-deploys an API reference site to GitHub Pages every time the main branch is updated via a GitHub Actions workflow.
More examples
Enable Pages from docs/ folder
Configures Pages to serve from the docs/ folder on main, then commits the first HTML file which GitHub will publish automatically.
# Enable via GitHub CLI
gh api repos/{owner}/{repo}/pages \
--method POST \
-f source.branch=main \
-f source.path="/docs"
# Add a simple index page
mkdir docs && echo '<h1>Hello GitHub Pages</h1>' > docs/index.html
git add docs/ && git commit -m "docs: add GitHub Pages site"
git pushDeploy with a GitHub Actions workflow
An Actions workflow that builds and deploys from the docs/ directory to GitHub Pages every time main is updated.
name: Deploy Docs
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
permissions:
pages: write
id-token: write
steps:
- uses: actions/checkout@v4
- uses: actions/configure-pages@v4
- uses: actions/upload-pages-artifact@v3
with:
path: ./docs
- uses: actions/deploy-pages@v4Set a custom domain for Pages
A CNAME file in the published folder tells GitHub Pages to serve the site under your own domain name instead of the default github.io URL.
# Add CNAME file to the site root
echo 'docs.myproject.com' > docs/CNAME
git add docs/CNAME
git commit -m "chore: set custom domain for Pages"
git push
Discussion