Build Hugo twice in GitHub Actions deployment workflows (#6655)

* Build Hugo twice in GitHub Actions deployment workflows, in order to support static Explore Docs menu * Fix bug for prod deploy second hugo build
linode · Oct 4, 2023 · de2a887 · de2a887
1 parent bd5266c
commit de2a887
Show file tree

Hide file tree

Showing 3 changed files with 155 additions and 79 deletions.
diff --git a/.github/workflows/deploy-to-feature-testing-server.yaml b/.github/workflows/deploy-to-feature-testing-server.yaml
@@ -138,6 +138,9 @@ jobs:
       working-directory: ./docs-repo
       run: npm ci
 
+      # When Hugo builds, it renders search index data to a collection of
+      # data files under public/. This step uploads that data to the
+      # Algolia search backend
     - name: Build Hugo
       env:
         HUGOxPARAMSxSEARCH_CONFIG2xAPP_ID: ${{ vars.ALGOLIA_APP_ID }}
@@ -157,6 +160,55 @@ jobs:
         sudo apt install -y tree
         tree -L 1 public
 
+    - name: Update Algolia (sandbox)
+      working-directory: ./linode-docs-theme-repo
+      env:
+        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
+        ALGOLIA_INDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
+      run: |
+        cd scripts/linode_algolia_admin/
+
+        # The testing-docs-prefix-update sequence does the following:
+        # - Downloads data from the starter_ prefixed linode-wp,
+        #   linode-community, and linode-documentation-sections indices to the
+        #   GitHub Action workspace
+        # - Pushes the rendered index JSON files under the public/ folder
+        #   in the docs repo from Hugo to Algolia. These are:
+        #   - public/index.json
+        #   - public/api/index.json
+        #   - public/data/sections/index.json
+        # - Merge the data from the separate indices and push it into the
+        #   PREFIX_linode-merged index in Algolia
+        # - Update the settings and synonyms for the PREFIX_linode-merged index
+        #   in Algolia
+        # - Delete the PREFIX_linode-documentation and
+        #   PREFIX_linode-documentation-api indices in Algolia to save space
+        go run main.go sequence -source-dir ../../../docs-repo/public testing-docs-prefix-update $ALGOLIA_INDEX_PREFIX
+
+      # Why build Hugo twice? In order to render the Explore Docs nav menu,
+      # Hugo downloads data from the Algolia search backend. However, the
+      # first time we build Hugo in this workflow, that data isn't up-to-date
+      # with new content we may be publishing. So, we build Hugo a second time
+      # after we have performed the previous Update Algolia step.
+      # In summary:
+      # - Build Hugo the first time in order to render the JSON search index
+      #   data files
+      # - Update Algolia with those data files
+      # - Build Hugo again so that the navigation UI can be rendered with that
+      #   updated info from Algolia
+      # It's a little redundant, but solves the chicken-or-egg problem
+    - name: Build Hugo (second time)
+      env:
+        HUGOxPARAMSxSEARCH_CONFIG2xAPP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        HUGOxPARAMSxSEARCH_CONFIG2xAPI_KEY: ${{ vars.ALGOLIA_SEARCH_KEY }}
+        HUGOxPARAMSxSEARCH_CONFIG2xINDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
+        HUGO_ENVIRONMENT: ${{ vars.HUGO_ENVIRONMENT }}
+      working-directory: ./docs-repo
+      run: |
+        hugo config
+        hugo -b "${{ secrets.DOCS_WEBSITE_URL }}" --gc --minify -d public
+
     - name: Set up SSH agent (docs webserver key)
       uses: webfactory/[email protected]
       with:
@@ -190,30 +242,4 @@ jobs:
           docs-repo/public/ \
           ${{ secrets.DOCS_WEBSITE_USER }}@${{ secrets.DOCS_WEBSITE_RSYNC_DESTINATION }}:${{ secrets.DOCS_WEBSITE_RSYNC_DIR }}
 
-        rm rsync_known_hosts
-
-    - name: Update Algolia (sandbox)
-      working-directory: ./linode-docs-theme-repo
-      env:
-        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
-        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
-        ALGOLIA_INDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
-      run: |
-        cd scripts/linode_algolia_admin/
-
-        # The testing-docs-prefix-update sequence does the following:
-        # - Downloads data from the starter_ prefixed linode-wp,
-        #   linode-community, and linode-documentation-sections indices to the
-        #   GitHub Action workspace
-        # - Pushes the rendered index JSON files under the public/ folder
-        #   in the docs repo from Hugo to Algolia. These are:
-        #   - public/index.json
-        #   - public/api/index.json
-        #   - public/data/sections/index.json
-        # - Merge the data from the separate indices and push it into the
-        #   PREFIX_linode-merged index in Algolia
-        # - Update the settings and synonyms for the PREFIX_linode-merged index
-        #   in Algolia
-        # - Delete the PREFIX_linode-documentation and
-        #   PREFIX_linode-documentation-api indices in Algolia to save space
-        go run main.go sequence -source-dir ../../../docs-repo/public testing-docs-prefix-update $ALGOLIA_INDEX_PREFIX
+        rm rsync_known_hosts
diff --git a/.github/workflows/deploy-to-main-staging-server.yaml b/.github/workflows/deploy-to-main-staging-server.yaml
@@ -157,6 +157,58 @@ jobs:
         sudo apt install -y tree
         tree -L 1 public
 
+      # When Hugo builds, it renders search index data to a collection of
+      # data files under public/. This step uploads that data to the
+      # Algolia search backend
+    - name: Update Algolia (sandbox)
+      working-directory: ./linode-docs-theme-repo
+      env:
+        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
+        ALGOLIA_INDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
+      run: |
+        cd scripts/linode_algolia_admin/
+
+        # The testing-docs-prefix-update sequence does the following:
+        # - Downloads data from the starter_ prefixed linode-wp,
+        #   linode-community, and linode-documentation-sections indices to the
+        #   GitHub Action workspace
+        # - Pushes the rendered index JSON files under the public/ folder
+        #   in the docs repo from Hugo to Algolia. These are:
+        #   - public/index.json
+        #   - public/api/index.json
+        #   - public/data/sections/index.json
+        # - Merge the data from the separate indices and push it into the
+        #   PREFIX_linode-merged index in Algolia
+        # - Update the settings and synonyms for the PREFIX_linode-merged index
+        #   in Algolia
+        # - Delete the PREFIX_linode-documentation and
+        #   PREFIX_linode-documentation-api indices in Algolia to save space
+        go run main.go sequence -source-dir ../../../docs-repo/public testing-docs-prefix-update $ALGOLIA_INDEX_PREFIX
+
+      # Why build Hugo twice? In order to render the Explore Docs nav menu,
+      # Hugo downloads data from the Algolia search backend. However, the
+      # first time we build Hugo in this workflow, that data isn't up-to-date
+      # with new content we may be publishing. So, we build Hugo a second time
+      # after we have performed the previous Update Algolia step.
+      # In summary:
+      # - Build Hugo the first time in order to render the JSON search index
+      #   data files
+      # - Update Algolia with those data files
+      # - Build Hugo again so that the navigation UI can be rendered with that
+      #   updated info from Algolia
+      # It's a little redundant, but solves the chicken-or-egg problem
+    - name: Build Hugo (second time)
+      env:
+        HUGOxPARAMSxSEARCH_CONFIG2xAPP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        HUGOxPARAMSxSEARCH_CONFIG2xAPI_KEY: ${{ vars.ALGOLIA_SEARCH_KEY }}
+        HUGOxPARAMSxSEARCH_CONFIG2xINDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
+        HUGO_ENVIRONMENT: ${{ vars.HUGO_ENVIRONMENT }}
+      working-directory: ./docs-repo
+      run: |
+        hugo config
+        hugo -b "${{ secrets.DOCS_WEBSITE_URL }}" --gc --minify -d public
+
     - name: Set up SSH agent (docs webserver key)
       uses: webfactory/[email protected]
       with:
@@ -190,30 +242,4 @@ jobs:
           docs-repo/public/ \
           ${{ secrets.DOCS_WEBSITE_USER }}@${{ secrets.DOCS_WEBSITE_RSYNC_DESTINATION }}:${{ secrets.DOCS_WEBSITE_RSYNC_DIR }}
 
-        rm rsync_known_hosts
-
-    - name: Update Algolia (sandbox)
-      working-directory: ./linode-docs-theme-repo
-      env:
-        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
-        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
-        ALGOLIA_INDEX_PREFIX: ${{ vars.ALGOLIA_INDEX_PREFIX }}
-      run: |
-        cd scripts/linode_algolia_admin/
-
-        # The testing-docs-prefix-update sequence does the following:
-        # - Downloads data from the starter_ prefixed linode-wp,
-        #   linode-community, and linode-documentation-sections indices to the
-        #   GitHub Action workspace
-        # - Pushes the rendered index JSON files under the public/ folder
-        #   in the docs repo from Hugo to Algolia. These are:
-        #   - public/index.json
-        #   - public/api/index.json
-        #   - public/data/sections/index.json
-        # - Merge the data from the separate indices and push it into the
-        #   PREFIX_linode-merged index in Algolia
-        # - Update the settings and synonyms for the PREFIX_linode-merged index
-        #   in Algolia
-        # - Delete the PREFIX_linode-documentation and
-        #   PREFIX_linode-documentation-api indices in Algolia to save space
-        go run main.go sequence -source-dir ../../../docs-repo/public testing-docs-prefix-update $ALGOLIA_INDEX_PREFIX
+        rm rsync_known_hosts
diff --git a/.github/workflows/deploy-to-production.yaml b/.github/workflows/deploy-to-production.yaml
@@ -152,6 +152,54 @@ jobs:
         sudo apt install -y tree
         tree -L 1 public
 
+      # When Hugo builds, it renders search index data to a collection of
+      # data files under public/. This step uploads that data to the
+      # Algolia search backend
+    - name: Update Algolia
+      working-directory: ./linode-docs-theme-repo
+      env:
+        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
+      run: |
+        cd scripts/linode_algolia_admin/
+
+        # Hugo renders the site to the `public` directory within the docs repo.
+        # This includes three files with Algolia index data:
+        # - public/index.json
+        # - public/api/index.json
+        # - public/data/sections/index.json
+        # The pushdocs command uploads this data to Algolia
+        go run main.go pushdocs -source-dir ../../../docs-repo/public
+
+        # The settings (e.g. ranking configuration) and synonyms for the
+        # linode-merged index are stored in version control, and the
+        # following command pushes those settings/synonyms to the Algolia app
+        go run main.go -indices linode-merged push -replace settings,synonyms
+
+        # The refresh-merge-and-push sequence assumes that the linode-wp and linode-community indices already exist in the Algolia app
+        go run main.go sequence refresh-merge-and-push
+
+      # Why build Hugo twice? In order to render the Explore Docs nav menu,
+      # Hugo downloads data from the Algolia search backend. However, the
+      # first time we build Hugo in this workflow, that data isn't up-to-date
+      # with new content we may be publishing. So, we build Hugo a second time
+      # after we have performed the previous Update Algolia step.
+      # In summary:
+      # - Build Hugo the first time in order to render the JSON search index
+      #   data files
+      # - Update Algolia with those data files
+      # - Build Hugo again so that the navigation UI can be rendered with that
+      #   updated info from Algolia
+      # It's a little redundant, but solves the chicken-or-egg problem
+    - name: Build Hugo (second time)
+      env:
+        HUGOxPARAMSxSEARCH_CONFIG2xAPP_ID: ${{ vars.ALGOLIA_APP_ID }}
+        HUGOxPARAMSxSEARCH_CONFIG2xAPI_KEY: ${{ vars.ALGOLIA_SEARCH_KEY }}
+      working-directory: ./docs-repo
+      run: |
+        hugo config
+        hugo -b "${{ vars.DOCS_WEBSITE_URL }}" --gc --minify -d public
+
     - name: Set up SSH agent (docs webserver key)
       uses: webfactory/[email protected]
       with:
@@ -191,28 +239,4 @@ jobs:
         rsync_to_destination "${{ secrets.DOCS_WEBSITE_RSYNC_DESTINATION_1 }}"
         rsync_to_destination "${{ secrets.DOCS_WEBSITE_RSYNC_DESTINATION_2 }}"
 
-        rm rsync_known_hosts
-
-    - name: Update Algolia
-      working-directory: ./linode-docs-theme-repo
-      env:
-        ALGOLIA_APP_ID: ${{ vars.ALGOLIA_APP_ID }}
-        ALGOLIA_ADMIN_API_KEY: ${{ secrets.ALGOLIA_WRITE_KEY }}
-      run: |
-        cd scripts/linode_algolia_admin/
-
-        # Hugo renders the site to the `public` directory within the docs repo.
-        # This includes three files with Algolia index data:
-        # - public/index.json
-        # - public/api/index.json
-        # - public/data/sections/index.json
-        # The pushdocs command uploads this data to Algolia
-        go run main.go pushdocs -source-dir ../../../docs-repo/public
-
-        # The settings (e.g. ranking configuration) and synonyms for the
-        # linode-merged index are stored in version control, and the
-        # following command pushes those settings/synonyms to the Algolia app
-        go run main.go -indices linode-merged push -replace settings,synonyms
-
-        # The refresh-merge-and-push sequence assumes that the linode-wp and linode-community indices already exist in the Algolia app
-        go run main.go sequence refresh-merge-and-push
+        rm rsync_known_hosts