Configure GHA to scan for spelling errors and broken links

.github/workflows/check-links-and-spelling.yml

@@ -0,0 +1,91 @@
+###############################################################################
+# Introduction:
+# -------------
+# This workflow builds the NMDC documentation, checks for broken links,
+# and identifies any spelling errors in the documentation.
+# If any issues are found (broken links or misspelled words), it creates
+# GitHub Issues containing lists of the errors for further review and fixing.
+#
+###############################################################################
+
+name: Check Links and Spelling in Documentation
+
+on:
+  # FIXME: Revert the branch name here to its original value.
+  push: { branches: [ 61-add-link-checker ] }
+  workflow_dispatch: { }
+  workflow_call: { }
+  # pull_request:
+  #   branches: [main]
+
+jobs:
+  check-links:
+    name: Check Links in Documentation
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write # required for peter-evans/create-issue-from-file
+    steps:
+      - name: Get website file tree
+        uses: actions/download-artifact@v4
+        with:
+          path: _build/html
+
+      # Note: Most of this snippet was copied from https://github.com/microbiomedata/nmdc-schema/blob/9c663673f3110a31f3a54a26a0698211c42b6143/.github/workflows/check-links.yaml#L38C1-L58C45.
+      #       A few parts were copied from https://github.com/lycheeverse/lychee-action.
+      - name: Use Lychee to check for broken links
+        # This step will populate `env.lychee_exit_code` with the exit code returned by lychee.
+        # Possible exit codes: https://github.com/lycheeverse/lychee?tab=readme-ov-file#exit-codes
+        # Reference: https://github.com/lycheeverse/lychee-action
+        id: lychee
+        uses: lycheeverse/[email protected]
+        with:
+          # Reference: https://github.com/lycheeverse/lychee#commandline-parameters
+          args: --base docs --verbose --no-progress --format markdown --timeout 5 '_build/html/**/*.html'
+          debug: true
+          output: ./lychee/out.md
+          fail: false
+      - name: Create GitHub Issue listing broken links
+        # This step will only run if lychee returned a non-zero exit code.
+        # Reference: https://docs.github.com/en/actions/learn-github-actions/variables#using-the-env-context-to-access-environment-variable-values
+        if: steps.lychee.outputs.exit_code != 0
+        uses: peter-evans/create-issue-from-file@v5
+        with:
+          title: Website file tree contains broken links
+          content-filepath: ./lychee/out.md
+
+  check-spelling:
+    name: Check Spelling in Documentation
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out commit
+        uses: actions/checkout@v4
+      - name: Download final build artifact
+        uses: actions/download-artifact@v4
+        with:
+          path: _build/html
+      - name: Run Spell Checker
+        id: spellcheck
+        continue-on-error: true
+        # Source: https://github.com/tbroadley/spellchecker-cli and https://github.com/austenstone/spellchecker-cli-action-summary
+        # Based off: https://github.com/austenstone/spellchecker-cli-action-summary/blob/main/.github/workflows/spellcheck.yml
+        run: |
+          mkdir -p spellcheck_reports
+          npx -y spellchecker-cli \
+            --files _build/html/**/*.html \
+            --dictionaries .github/workflows/spellcheck_allow_list.txt \
+            --plugins spell indefinite-article repeated-words syntax-mentions syntax-urls \
+            --reports spellcheck_reports/spellcheck_report.json |
+            tee spellcheck_reports/spellcheck_output.txt
+          if grep -q 'misspelt' spellcheck_reports/spellcheck_report.json; then
+            echo "misspelt=true" >> $GITHUB_OUTPUT
+          else
+            echo "misspelt=false" >> $GITHUB_OUTPUT
+          fi
+
+      # - name: Create GitHub Issue for Misspellings
+      #   if: ${{ steps.spellcheck.outputs.misspelt == 'true' }}
+      #   uses: peter-evans/create-issue-from-file@v4
+      #   with:
+      #     title: Documentation contains misspelled words
+      #     content-filepath: spellcheck_reports/spellcheck_output.txt
+      #     labels: documentation, spelling-error

.github/workflows/deploy-to-gh-pages.yml

@@ -3,7 +3,7 @@
 name: Build and deploy to GitHub Pages
 
 on:
-  push: { branches: [ main ] }
+  push: { branches: [ 61-add-link-checker ] }
   workflow_dispatch: { }
 
 # Reference: https://docs.github.com/en/actions/using-jobs/using-concurrency
@@ -62,20 +62,26 @@ jobs:
         with:
           path: _build/html
 
-  deploy:
-    name: Deploy website
-    needs:
-      - build
-    runs-on: ubuntu-latest
-    # Reference: https://github.com/actions/deploy-pages
-    permissions:
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      # Reference: https://github.com/actions/deploy-pages
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+  check-links-and-spelling:
+    name: Check Links and Spelling in Documentation
+    uses: ./.github/workflows/check-links-and-spelling.yml
+    needs: build
+
+
+  # deploy:
+  #   name: Deploy website
+  #   needs:
+  #     - build
+  #   runs-on: ubuntu-latest
+  #   # Reference: https://github.com/actions/deploy-pages
+  #   permissions:
+  #     pages: write
+  #     id-token: write
+  #   environment:
+  #     name: github-pages
+  #     url: ${{ steps.deployment.outputs.page_url }}
+  #   steps:
+  #     # Reference: https://github.com/actions/deploy-pages
+  #     - name: Deploy to GitHub Pages
+  #       id: deployment
+  #       uses: actions/deploy-pages@v4

.github/workflows/mlc_config.json

@@ -0,0 +1,7 @@
+{
+    "timeout": "20s",
+    "retryOn429": true,
+    "retryCount": 5,
+    "fallbackRetryDelay": "30s",
+    "aliveStatusCodes": [200, 206]
+  }

.github/workflows/spellcheck_allow_list.txt

@@ -0,0 +1,36 @@
+Bioinformatics
+bioinformatics
+Biosample
+biosample
+Changesheets
+changesheets
+Community-centric
+community-centric
+Diátaxis
+Globus
+IMG
+JSON
+json
+Lipidomics
+lipidomics
+Metabolomics
+metabolomics
+MetaG
+Metagenome
+metagenome
+Metagenomic
+metagenomic
+Metaproteomic
+MetaT
+Metatranscriptome
+metatranscriptome
+Metatranscriptomic
+metatranscriptomic
+Microbiome
+microbiome
+Mgt
+MkDocs
+multi-omics
+NMDC
+NMDC's
+nmdc-runtime