1. Docs
2. Getting started

Publish

Your site on GitHub Pages, rebuilt by itself on every change.

GitHub Pages hosts static sites for free. A workflow (a recipe GitHub runs for you) builds the site with Hugo every time you push a change, and publishes it.

Put the site on GitHub#

1. Create a free account at github.com (opens in a new tab) and a new repository, for example my-site, without a README.

2. In your site’s folder, add a .gitignore file, so Hugo’s output and your secrets stay out of the repository:

   public/
   resources/
   .hugo_build.lock
   .env

3. Commit and push (GitHub shows these commands after you create the repository):

   git add .
   git commit -m "My site"
   git branch -M main
   git remote add origin https://github.com/you/my-site.git
   git push -u origin main

The workflow#

In your repository on GitHub: Settings → Pages → Source: GitHub Actions. Then add this file to your site and push it:

name: Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          submodules: recursive   # only needed if you added the theme as a Git submodule
      - uses: actions/setup-go@v5
        with:
          go-version: stable
      - name: Install Hugo
        run: |
          curl -sSL -o "$RUNNER_TEMP/hugo.deb" https://github.com/gohugoio/hugo/releases/download/v0.167.0/hugo_extended_0.167.0_linux-amd64.deb
          sudo dpkg -i "$RUNNER_TEMP/hugo.deb"
      - uses: actions/configure-pages@v5
        id: pages
      - name: Build
        run: hugo --minify --baseURL "${{ steps.pages.outputs.base_url }}/"
        env:
          HUGO_MAPTILER_KEY: ${{ secrets.MAPTILER_KEY }}   # for trip maps; see Trip maps
      - uses: actions/upload-pages-artifact@v3
        with:
          path: public

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - id: deployment
        uses: actions/deploy-pages@v4

Under Actions in your repository you can watch it run. When it’s done, the site is at https://you.github.io/my-site/, and every push updates it within a minute or two.

Your own domain#

Under Settings → Pages → Custom domain, enter it, for example jane.example.org, and add the DNS record GitHub asks for at your domain’s provider (a CNAME record pointing to you.github.io). The workflow takes the new address by itself.

Other hosts#

Netlify, Cloudflare Pages and Vercel build Hugo sites too. Connect your repository, with hugo --minify as the build command and public as the output folder; set the environment variables HUGO_VERSION (0.167.0) and, for maps, HUGO_MAPTILER_KEY.