GitHub actions: deployment to GitHub Pages, link check

* added workflow files
* README.md:
  - added section on deployment via GitHub pages
  - added section on automated link checking

Author: deining

.github/workflows/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@v3
+        with:
+          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.110.0'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          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@v3
+        if: ${{ github.ref == 'refs/heads/master' }} # <- must be same branch as given above
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./public

.github/workflows/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@v3
+        with:
+          fetch-depth: 0         # Fetch all history for .GitInfo and .Lastmod
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: '0.110.0'
+          extended: true
+
+      - name: Setup Node
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18'
+          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

@@ -61,6 +61,28 @@ 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, edit the corresponding [workflow file](.github/workflows/deploy-github-pages.yml) 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.
+By default, 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/)
@@ -140,9 +162,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
@@ -152,3 +173,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/deploy-github-pages.yml
+[link check workflow]: ../../actions/workflows/link-check.yml
+[hyperlink]: https://github.com/untitaker/hyperlink
+[download area]: https://go.dev/dl/

hugo.toml

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