Debian Codegraph @

docs/content/en/host-and-deploy/host-on-github-pages/index.md

raw
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 ![screen capture](gh-pages-01.png)
33
34 Change the **Source** to `GitHub Actions`. The change is immediate; you do not have to press a Save button.
35
36 ![screen capture](gh-pages-02.png)
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 ![screen capture](gh-pages-03.png)
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 ![screen capture](gh-pages-04.png)
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 ![screen capture](gh-pages-05.png)
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