GitHub actions: deployment to GitHub Pages, link check

.github/workflows/README.md

@@ -0,0 +1,19 @@
+## Automated deployment on GitHub pages on each commit and/or pull request
+
+To enable automatic deployment on each push to your repo, move the the corresponding [workflow file](.github/workflows/example/deploy-github-pages.yml) into this folder `.github/workflows`.
+
+```
+mv example/deploy-github-pages.yml .
+```
+
+For further details, refer to the section `` in the `REDAME.md file located in the root of this repo.
+
+## Automated link check on each commit and/or pull request
+
+Inside the example subdirectory, you will find a GitHub action file that allows you to check the internal links of your page using the fast [hyperlink](https://github.com/untitaker/hyperlink) link checker. To enable automatic link checking on each push to your repo, move the the corresponding [workflow file](example/link-check.yml) into this folder `.github/workflows`. 
+
+```
+mv example/link-check.yml .
+```
+
+Afterwards, the link check action will be performed on each push to your repo.

.github/workflows/example/deploy-github-pages.yml

@@ -0,0 +1,50 @@
+name: Deployment on GitHub Pages
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      # uncomment line below for automatic deployment on push
+      # - master  # <- Set branch used for deployment
+  pull_request:
+
+env:
+  REPO_NAME: ${{ github.event.repository.name }}
+  REPO_OWNER: ${{ github.repository_owner }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    concurrency:
+      group: deployment-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: '0.136.5'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          # The action defaults to search for the dependency file (package-lock.json,
+          # npm-shrinkwrap.json or yarn.lock) in the repository root, and uses its
+          # hash as a part of the cache key.
+          # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
+          cache-dependency-path: '**/package-lock.json'
+
+      - run: npm ci
+      - run: hugo --baseURL https://${REPO_OWNER}.github.io/${REPO_NAME} --minify
+
+      - name: Deployment
+        uses: peaceiris/actions-gh-pages@v4
+        if: ${{ github.ref == 'refs/heads/master' }} # <- must be same branch as given above
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.github/workflows/example/link-check.yml

@@ -0,0 +1,46 @@
+name: Link check
+
+on:
+  workflow_call:
+  push:
+    branches:
+      - master  # <- Set branch used for deployment
+  pull_request:
+
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-22.04
+    concurrency:
+      group: link-check-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v3
+        with:
+          hugo-version: '0.136.5'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+          # The action defaults to search for the dependency file (package-lock.json,
+          # npm-shrinkwrap.json or yarn.lock) in the repository root, and uses its
+          # hash as a part of the cache key.
+          # https://github.com/actions/setup-node/blob/main/docs/advanced-usage.md#caching-packages-data
+          cache-dependency-path: '**/package-lock.json'
+
+      - run: npm ci
+      - run: hugo --baseURL '' --minify
+
+      - name: Link check
+        uses: untitaker/[email protected]
+        if: ${{ github.ref == 'refs/heads/master' }} # <- must be same branch as given above
+        with:
+          args: public/ # --check-anchors

.gitignore

@@ -1,5 +1,4 @@
 /public
 resources/
 node_modules/
-package-lock.json
 .hugo_build.lock

README.md

@@ -57,6 +57,27 @@ Once you've made your working copy of the site repo, from the repo root folder,
 hugo server
 ```
 
+## Deployment on GitHub pages
+
+This repo ships with a [GitHub action] that allows you to deploy your site to [GitHub Pages].
+To manually trigger the deployment, select the [deployment workflow] in the `Actions` section of the GitHub web UI and press the button `Run workflow`.
+To enable automatic deployment on each push to your repo, move the the corresponding [workflow file](.github/workflows/example/deploy-github-pages.yml) to the folder `.github/workflows` of your repo. Afterwards, edit  and uncomment the line specifying the branch used for deployment:
+
+```yml
+on:
+  workflow_dispatch:   # enables manual run of workflow via GitHub web UI
+  push:
+    branches:
+      - master        # <- Set branch used for deployment here
+```
+
+For further details on the deployment setup, please refer to the [deployment] section of the docsy user guide.
+
+## Automated link check
+
+This repo ships with a [GitHub action] that allows you to check the internal links of your page using the fast [hyperlink] link checker. To enable automatic link checking on each push to your repo, move the the corresponding [workflow file](.github/workflows/example/link-check.yml) to the folder `.github/workflows` of you repo. Afterwards, the link check action will be performed on each push to your repo. To see the results of the last workflow run(s), select the [link check workflow] in the `Actions` section of the GitHUB web UI.
+On the same page, you can also disable the workflow if needed. To do so, press the button `…` right beneath the search field that allows you to filter workflow runs.
+
 ## Running a container locally
 
 You can run docsy-example inside a [Docker](https://docs.docker.com/)
@@ -106,7 +127,7 @@ Clone the latest version of the docsy theme into the parent folder of your proje
 
 ```shell
 cd root-of-your-site
-git clone --branch v0.7.2 https://github.com/google/docsy.git ../docsy
+git clone --branch v0.11.0 https://github.com/google/docsy.git ../docsy
 ```
 
 Now run:
@@ -159,7 +180,7 @@ Built in 288 ms
 Error: Error building site: TOCSS: failed to transform "scss/main.scss" (text/x-scss): resource "scss/scss/main.scss_9fadf33d895a46083cdd64396b57ef68" not found in file cache
 ```
 
-This error occurs if you have not installed the extended version of Hugo.
+This error occurs if you do not have the extended version of Hugo installed.
 See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-hugo) of the user guide for instructions on how to install Hugo.
 
 Or you may encounter the following error:
@@ -170,9 +191,8 @@ $ hugo server
 Error: failed to download modules: binary with name "go" not found
 ```
 
-This error occurs if you have not installed the `go` programming language on your system.
-See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/installation-prerequisites/#install-go-language) of the user guide for instructions on how to install `go`.
-
+This error occurs if the `go` programming language is not available on your system.
+Go to the [download area] of the Go website, choose the installer for your system architecture and execute it.
 
 [alternate dashboard]: https://app.netlify.com/sites/goldydocs/deploys
 [deploys]: https://app.netlify.com/sites/docsy-example/deploys
@@ -182,3 +202,9 @@ See this [section](https://www.docsy.dev/docs/get-started/docsy-as-module/instal
 [Hugo theme module]: https://gohugo.io/hugo-modules/use-modules/#use-a-module-for-a-theme
 [Netlify]: https://netlify.com
 [Docker Compose documentation]: https://docs.docker.com/compose/gettingstarted/
+[GitHub action]: https://docs.github.com/en/actions
+[deployment]: https://docsy.dev/docs/deployment/#deployment-on-github-pages
+[deployment workflow]: ../../actions/workflows/example/deploy-github-pages.yml
+[link check workflow]: ../../actions/workflows/example/link-check.yml
+[hyperlink]: https://github.com/untitaker/hyperlink
+[download area]: https://go.dev/dl/

hugo-disabled.toml

@@ -1,4 +1,7 @@
 baseURL = "https://example.docsy.dev/"
+# For deployment on GitHub Pages:
+# baseURL = "https://<USERNAME>.github.io/<repository_name>"
+
 title = "Goldydocs"
 
 # Language settings

hugo.yaml

@@ -1,4 +1,7 @@
 baseURL: https://example.docsy.dev
+# For deployment on GitHub Pages:
+# baseURL: https://<USERNAME>.github.io/<repository_name>
+
 title: Goldydocs
 
 # cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu