From 9ca7bbc48bc38153c5d9a7c070e437789a555096 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Wed, 22 Feb 2023 10:57:40 +0100 Subject: [PATCH 1/3] 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 --- .github/workflows/deploy-github-pages.yml | 50 +++++++++++++++++++++++ .github/workflows/link-check.yml | 46 +++++++++++++++++++++ .gitignore | 1 - README.md | 33 +++++++++++++-- hugo-disabled.toml | 3 ++ 5 files changed, 129 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/deploy-github-pages.yml create mode 100644 .github/workflows/link-check.yml diff --git a/.github/workflows/deploy-github-pages.yml b/.github/workflows/deploy-github-pages.yml new file mode 100644 index 00000000000..c4b20594fb0 --- /dev/null +++ b/.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 diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml new file mode 100644 index 00000000000..2e82a33cd4e --- /dev/null +++ b/.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/hyperlink@0.1.27 + if: ${{ github.ref == 'refs/heads/master' }} # <- must be same branch as given above + with: + args: public/ # --check-anchors diff --git a/.gitignore b/.gitignore index 40b67f41a76..aebf6616c10 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,4 @@ /public resources/ node_modules/ -package-lock.json .hugo_build.lock \ No newline at end of file diff --git a/README.md b/README.md index 481ce674132..f48c5df4c3f 100644 --- a/README.md +++ b/README.md @@ -57,6 +57,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/) @@ -170,9 +192,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 +203,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/ \ No newline at end of file diff --git a/hugo-disabled.toml b/hugo-disabled.toml index 12b2be89306..8b053186648 100644 --- a/hugo-disabled.toml +++ b/hugo-disabled.toml @@ -1,4 +1,7 @@ baseURL = "https://example.docsy.dev/" +# For deployment on GitHub Pages: +# baseURL = "https://.github.io/" + title = "Goldydocs" # Language settings From 22cf7df2134e19bebea5aba5542ca3298c155ee0 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 31 Oct 2024 11:54:39 +0100 Subject: [PATCH 2/3] Update workflow actions and dependencies --- .github/workflows/deploy-github-pages.yml | 12 ++++++------ .github/workflows/link-check.yml | 12 ++++++------ hugo.yaml | 3 +++ 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/.github/workflows/deploy-github-pages.yml b/.github/workflows/deploy-github-pages.yml index c4b20594fb0..e8d151b195e 100644 --- a/.github/workflows/deploy-github-pages.yml +++ b/.github/workflows/deploy-github-pages.yml @@ -18,20 +18,20 @@ jobs: concurrency: group: deployment-${{ github.ref }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 + uses: peaceiris/actions-hugo@v3 with: - hugo-version: '0.110.0' + hugo-version: '0.136.5' extended: true - name: Setup Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: - node-version: '18' + 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 @@ -43,7 +43,7 @@ jobs: - run: hugo --baseURL https://${REPO_OWNER}.github.io/${REPO_NAME} --minify - name: Deployment - uses: peaceiris/actions-gh-pages@v3 + 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 }} diff --git a/.github/workflows/link-check.yml b/.github/workflows/link-check.yml index 2e82a33cd4e..9cf5f6324bc 100644 --- a/.github/workflows/link-check.yml +++ b/.github/workflows/link-check.yml @@ -15,20 +15,20 @@ jobs: concurrency: group: link-check-${{ github.ref }} steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 with: fetch-depth: 0 # Fetch all history for .GitInfo and .Lastmod - name: Setup Hugo - uses: peaceiris/actions-hugo@v2 + uses: peaceiris/actions-hugo@v3 with: - hugo-version: '0.110.0' + hugo-version: '0.136.5' extended: true - name: Setup Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: - node-version: '18' + 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 @@ -40,7 +40,7 @@ jobs: - run: hugo --baseURL '' --minify - name: Link check - uses: untitaker/hyperlink@0.1.27 + uses: untitaker/hyperlink@0.1.42 if: ${{ github.ref == 'refs/heads/master' }} # <- must be same branch as given above with: args: public/ # --check-anchors diff --git a/hugo.yaml b/hugo.yaml index fc0a6e7fb9c..516502ef7f2 100644 --- a/hugo.yaml +++ b/hugo.yaml @@ -1,4 +1,7 @@ baseURL: https://example.docsy.dev +# For deployment on GitHub Pages: +# baseURL: https://.github.io/ + title: Goldydocs # cSpell:ignore goldmark github hugo readingtime docsy subdir lastmod pygments linenos catmullrom norsk gu From a022419e25d8af5873e6f85c084bb21df8026364 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Thu, 31 Oct 2024 12:23:37 +0100 Subject: [PATCH 3/3] Move workflow file to .github/workflows/example --- .github/workflows/README.md | 19 +++++++++++++++++++ .../{ => example}/deploy-github-pages.yml | 0 .../workflows/{ => example}/link-check.yml | 0 README.md | 13 ++++++------- 4 files changed, 25 insertions(+), 7 deletions(-) create mode 100644 .github/workflows/README.md rename .github/workflows/{ => example}/deploy-github-pages.yml (100%) rename .github/workflows/{ => example}/link-check.yml (100%) diff --git a/.github/workflows/README.md b/.github/workflows/README.md new file mode 100644 index 00000000000..8e34a337158 --- /dev/null +++ b/.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. diff --git a/.github/workflows/deploy-github-pages.yml b/.github/workflows/example/deploy-github-pages.yml similarity index 100% rename from .github/workflows/deploy-github-pages.yml rename to .github/workflows/example/deploy-github-pages.yml diff --git a/.github/workflows/link-check.yml b/.github/workflows/example/link-check.yml similarity index 100% rename from .github/workflows/link-check.yml rename to .github/workflows/example/link-check.yml diff --git a/README.md b/README.md index f48c5df4c3f..fe1635fce61 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ hugo server 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: +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: @@ -75,8 +75,7 @@ For further details on the deployment setup, please refer to the [deployment] se ## 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. +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 @@ -128,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: @@ -181,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: @@ -205,7 +204,7 @@ Go to the [download area] of the Go website, choose the installer for your syste [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 +[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/ \ No newline at end of file