diff --git a/.github/workflows/hugo.yml b/.github/workflows/hugo.yml index 0b48e6c8a62..170ef2e14e7 100644 --- a/.github/workflows/hugo.yml +++ b/.github/workflows/hugo.yml @@ -2,12 +2,19 @@ name: Generate and upload Hugo docs on: push: - branches: master + +# Set permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages for doc reviews +permissions: + contents: read + pages: write + id-token: write jobs: - ocaml: + hugo: name: Docs runs-on: ubuntu-22.04 + concurrency: + group: ${{ github.workflow }}-${{ github.ref }} steps: - name: Checkout code @@ -16,15 +23,21 @@ jobs: - name: Setup Hugo uses: peaceiris/actions-hugo@v3 with: - hugo-version: '0.119.0' + hugo-version: '0.127.0' - - name: Build + - name: Build with defaults from doc/hugo.yml for the xapi-project/xen-api master + if: | + github.repository == 'xapi-project/xen-api' && + github.ref == 'refs/heads/master' run: | cd doc hugo --minify - - name: Deploy + - name: Deploy xapi-project/xen-api master to https://xapi-project.github.io/new-docs uses: peaceiris/actions-gh-pages@v4 + if: | + github.repository == 'xapi-project/xen-api' && + github.ref == 'refs/heads/master' with: deploy_key: ${{ secrets.ACTIONS_DOCS_DEPLOY_KEY }} publish_dir: ./doc/public @@ -35,3 +48,29 @@ jobs: destination_dir: new-docs # temporary staging branch allow_empty_commit: false enable_jekyll: true # do not create .nojekyll file + + - name: Build to deploy to a clone's GitHub Pages for documentation update reviews + if: github.repository != 'xapi-project/xen-api' + env: + # Override the Hugo baseUrl in doc/hugo.toml with the repo name for doc reviews: + HUGO_BASEURL: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/ + run: cd doc;hugo --minify + + - name: Upload Hugo static site as an artifact for documentation update reviews + if: github.repository != 'xapi-project/xen-api' + uses: actions/upload-pages-artifact@v3 + with: + path: ./doc/public + + # When pushed to other repositories, deploy to the repository's GitHub Pages + deploy: + needs: hugo + if: github.repository != 'xapi-project/xen-api' + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - name: Deploy uploaded artifact to GitHub Pages for documentation update reviews + id: deployment + uses: actions/deploy-pages@v4 diff --git a/doc/hugo.toml b/doc/hugo.toml index bb1127b019e..d7eb93250e4 100644 --- a/doc/hugo.toml +++ b/doc/hugo.toml @@ -9,10 +9,32 @@ assetsDir = "assets" [[module.imports]] path = 'github.com/McShelby/hugo-theme-relearn' +# The latest upstream version of hugo-theme-relearn needs hugo 0.121.0: +# https://mcshelby.github.io/hugo-theme-relearn/basics/requirements/index.html +[module.hugoVersion] + min = "0.121.0" + [outputs] -home = [ "HTML", "RSS", "SEARCH"] +# Home and section pages should also have a print icon for the print view: +home = [ "HTML", "RSS", "SEARCH", "PRINT"] +section = [ "HTML", "RSS", "PRINT"] [params] -themeVariant = "red" +# Enable the theme variant selector, default to auto: +themeVariant = [ + "auto", + "zen-light", + "zen-dark", + "red", + "blue", + "green", + "learn", + "neon", + "relearn-light", + "relearn-bright", + "relearn-dark" +] +# auto switches between "red" and "zen-dark" depending on the browser/OS dark mode: +themeVariantAuto = ["red", "zen-dark"] alwaysopen = false collapsibleMenu = true