| 1 |
--- |
| 2 |
title: Host on GitHub Pages |
| 3 |
description: Host your site on GitHub Pages. |
| 4 |
categories: [] |
| 5 |
keywords: [] |
| 6 |
aliases: [/hosting-and-deployment/hosting-on-github/] |
| 7 |
--- |
| 8 |
|
| 9 |
## Types of sites |
| 10 |
|
| 11 |
There are three types of GitHub Pages sites: project, user, and organization. Project sites are connected to a specific project hosted on GitHub. User and organization sites are connected to a specific account on GitHub.com. |
| 12 |
|
| 13 |
> [!note] |
| 14 |
> See the [GitHub Pages documentation] to understand the requirements for repository ownership and naming. |
| 15 |
|
| 16 |
## Prerequisites |
| 17 |
|
| 18 |
Please complete the following tasks before continuing: |
| 19 |
|
| 20 |
1. [Create](https://github.com/signup) a GitHub account |
| 21 |
1. [Log in](https://github.com/login) to your GitHub account |
| 22 |
1. [Create](https://github.com/new) a GitHub repository for your project |
| 23 |
1. [Create](https://git-scm.com/docs/git-init) a local Git repository for your project with a [remote](https://git-scm.com/docs/git-remote) reference to your GitHub repository |
| 24 |
1. Create a Hugo project within your local Git repository and test it with the `hugo server` command |
| 25 |
1. Commit the changes to your local Git repository and push to your GitHub repository |
| 26 |
|
| 27 |
## Procedure |
| 28 |
|
| 29 |
Step 1 |
| 30 |
: Visit your GitHub repository. From the main menu choose **Settings** > **Pages**. In the center of your screen you will see this: |
| 31 |
|
| 32 |
 |
| 33 |
|
| 34 |
Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button. |
| 35 |
|
| 36 |
 |
| 37 |
|
| 38 |
Step 2 |
| 39 |
: In your project configuration, change the location of the image cache to the [`cacheDir`] as shown below: |
| 40 |
|
| 41 |
{{< code-toggle file=hugo copy=true >}} |
| 42 |
[caches.images] |
| 43 |
dir = ':cacheDir/images' |
| 44 |
{{< /code-toggle >}} |
| 45 |
|
| 46 |
See [configure file caches] for more information. |
| 47 |
|
| 48 |
Step 3 |
| 49 |
: Create a file named `hugo.yaml` in a directory named `.github/workflows`. |
| 50 |
|
| 51 |
```text |
| 52 |
mkdir -p .github/workflows |
| 53 |
touch .github/workflows/hugo.yaml |
| 54 |
``` |
| 55 |
|
| 56 |
Step 4 |
| 57 |
: Copy and paste the YAML below into the file you created. |
| 58 |
|
| 59 |
```yaml {file=".github/workflows/hugo.yaml" copy=true} |
| 60 |
name: Build and deploy |
| 61 |
on: |
| 62 |
push: |
| 63 |
branches: |
| 64 |
- main |
| 65 |
workflow_dispatch: |
| 66 |
permissions: |
| 67 |
contents: read |
| 68 |
pages: write |
| 69 |
id-token: write |
| 70 |
concurrency: |
| 71 |
group: pages |
| 72 |
cancel-in-progress: false |
| 73 |
defaults: |
| 74 |
run: |
| 75 |
shell: bash |
| 76 |
jobs: |
| 77 |
build: |
| 78 |
runs-on: ubuntu-latest |
| 79 |
env: |
| 80 |
DART_SASS_VERSION: 1.99.0 |
| 81 |
GO_VERSION: 1.26.2 |
| 82 |
HUGO_VERSION: 0.161.1 |
| 83 |
NODE_VERSION: 24.15.0 |
| 84 |
TZ: Europe/Oslo |
| 85 |
steps: |
| 86 |
- name: Checkout |
| 87 |
uses: actions/checkout@v6 |
| 88 |
with: |
| 89 |
submodules: recursive |
| 90 |
fetch-depth: 0 |
| 91 |
- name: Setup Go |
| 92 |
uses: actions/setup-go@v6 |
| 93 |
with: |
| 94 |
go-version: ${{ env.GO_VERSION }} |
| 95 |
cache: false |
| 96 |
- name: Setup Node.js |
| 97 |
uses: actions/setup-node@v6 |
| 98 |
with: |
| 99 |
node-version: ${{ env.NODE_VERSION }} |
| 100 |
- name: Setup Pages |
| 101 |
id: pages |
| 102 |
uses: actions/configure-pages@v6 |
| 103 |
- name: Create directory for user-specific executable files |
| 104 |
run: | |
| 105 |
mkdir -p "${HOME}/.local" |
| 106 |
- name: Install Dart Sass |
| 107 |
run: | |
| 108 |
curl -sLJO "https://github.com/sass/dart-sass/releases/download/${DART_SASS_VERSION}/dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" |
| 109 |
tar -C "${HOME}/.local" -xf "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" |
| 110 |
rm "dart-sass-${DART_SASS_VERSION}-linux-x64.tar.gz" |
| 111 |
echo "${HOME}/.local/dart-sass" >> "${GITHUB_PATH}" |
| 112 |
- name: Install Hugo |
| 113 |
run: | |
| 114 |
curl -sLJO "https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" |
| 115 |
mkdir "${HOME}/.local/hugo" |
| 116 |
tar -C "${HOME}/.local/hugo" -xf "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" |
| 117 |
rm "hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz" |
| 118 |
echo "${HOME}/.local/hugo" >> "${GITHUB_PATH}" |
| 119 |
- name: Verify installations |
| 120 |
run: | |
| 121 |
echo "Dart Sass: $(sass --version)" |
| 122 |
echo "Go: $(go version)" |
| 123 |
echo "Hugo: $(hugo version)" |
| 124 |
echo "Node.js: $(node --version)" |
| 125 |
- name: Install Node.js dependencies |
| 126 |
run: | |
| 127 |
[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true |
| 128 |
- name: Configure Git |
| 129 |
run: | |
| 130 |
git config core.quotepath false |
| 131 |
- name: Cache restore |
| 132 |
id: cache-restore |
| 133 |
uses: actions/cache/restore@v5 |
| 134 |
with: |
| 135 |
path: ${{ runner.temp }}/hugo_cache |
| 136 |
key: hugo-${{ github.run_id }} |
| 137 |
restore-keys: |
| 138 |
hugo- |
| 139 |
- name: Build the site |
| 140 |
run: | |
| 141 |
hugo build \ |
| 142 |
--gc \ |
| 143 |
--minify \ |
| 144 |
--baseURL "${{ steps.pages.outputs.base_url }}/" \ |
| 145 |
--cacheDir "${{ runner.temp }}/hugo_cache" |
| 146 |
- name: Cache save |
| 147 |
id: cache-save |
| 148 |
uses: actions/cache/save@v5 |
| 149 |
with: |
| 150 |
path: ${{ runner.temp }}/hugo_cache |
| 151 |
key: ${{ steps.cache-restore.outputs.cache-primary-key }} |
| 152 |
- name: Upload artifact |
| 153 |
uses: actions/upload-pages-artifact@v5 |
| 154 |
with: |
| 155 |
path: ./public |
| 156 |
deploy: |
| 157 |
environment: |
| 158 |
name: github-pages |
| 159 |
url: ${{ steps.deployment.outputs.page_url }} |
| 160 |
runs-on: ubuntu-latest |
| 161 |
needs: build |
| 162 |
steps: |
| 163 |
- name: Deploy to GitHub Pages |
| 164 |
id: deployment |
| 165 |
uses: actions/deploy-pages@v5 |
| 166 |
``` |
| 167 |
|
| 168 |
Step 5 |
| 169 |
: Commit the changes to your local Git repository and push to your GitHub repository. |
| 170 |
|
| 171 |
Step 6 |
| 172 |
: From GitHub's main menu, choose **Actions**. You will see something like this: |
| 173 |
|
| 174 |
 |
| 175 |
|
| 176 |
Step 7 |
| 177 |
: When GitHub has finished building and deploying your site, the color of the status indicator will change to green. |
| 178 |
|
| 179 |
 |
| 180 |
|
| 181 |
Step 8 |
| 182 |
: Click on the commit message as shown above. Under the deploy step, you will see a link to your live site. |
| 183 |
|
| 184 |
 |
| 185 |
|
| 186 |
In the future, whenever you push a change from your local Git repository, GitHub Pages will rebuild and deploy your site. |
| 187 |
|
| 188 |
## Other resources |
| 189 |
|
| 190 |
- [Learn more about GitHub Actions](https://docs.github.com/en/actions) |
| 191 |
- [Caching dependencies to speed up workflows](https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows) |
| 192 |
- [Manage a custom domain for your GitHub Pages site](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages) |
| 193 |
|
| 194 |
[`cacheDir`]: /configuration/all/#cachedir |
| 195 |
[configure file caches]: /configuration/caches/ |
| 196 |
[GitHub Pages documentation]: https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites |