[v16] Edit docs CI workflows to accommodate Docusaurus

.github/workflows/doc-tests.yaml

@@ -44,23 +44,54 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          repository: "gravitational/docs"
-          path: "docs"
+          repository: 'gravitational/teleport'
+          path: 'teleport'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: 'gravitational/docs-website'
+          path: 'docs'
+
+      # Cache node_modules. Unlike the example in the actions/cache repo, this
+      # caches the node_modules directory instead of the yarn cache. This is
+      # because yarn needs to build fresh packages even when it copies files
+      # from the yarn cache into node_modules.
+      # See:
+      # https://github.com/actions/cache/blob/main/examples.md#node---yarn
+      - uses: actions/cache@v4
+        id: yarn-cache # use this to check for `cache-hit` (`steps.yarn-cache.outputs.cache-hit != 'true'`)
+        with:
+          path: '${{ github.workspace }}/docs/node_modules'
+          key: ${{ runner.os }}-yarn-${{ hashFiles(format('{0}/docs/yarn.lock', github.workspace)) }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Install docs site dependencies
+        working-directory: docs
+        if: ${{ steps.yarn-cache.outputs.cache-hit != 'true' }}
+        # Prevent occasional `yarn install` executions that run indefinitely
+        timeout-minutes: 10
+        run: yarn install
 
       - name: Prepare docs site configuration
         # The environment we use for linting the docs differs from the one we
         # use for the live docs site in that we only test a single version of
         # the content.
         #
-        # To do this, we replace the three submodules we use for building the
-        # live docs site with a single submodule, pointing to the
-        # gravitational/teleport branch we are linting.
-        #
+        # To do this, we delete the three submodules we use for building the
+        # live docs site and copy a gravitational/teleport clone into the
+        # content directory.
+        # 
         # The docs engine expects a config.json file at the root of the
         # gravitational/docs clone that associates directories with git
         # submodules. By default, these directories represent versioned branches
         # of gravitational/teleport. We override this in order to build only a
         # single version of the docs.
+        #
+        # We also replace data fetched from Sanity CMS with hardcoded JSON
+        # objects to remove the need to authenticate with Sanity. Each includes
+        # the minimal set of data required for docs builds to succeed.
         run: |
           if [ $GITHUB_EVENT_NAME = "pull_request" ]; then
             BRANCH=$GITHUB_HEAD_REF;
@@ -78,16 +109,19 @@ jobs:
           cd $GITHUB_WORKSPACE/docs
           echo "" > .gitmodules
           rm -rf content/*
-          cd content
-          # Add a submodule at docs/content/teleport
-          git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport
-          cd $GITHUB_WORKSPACE/docs
-          echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
-          yarn install
-          yarn build-node
+          # Rather than using a submodule, copy the teleport source into the
+          # content directory.
+          cp -r "$GITHUB_WORKSPACE/teleport" "$GITHUB_WORKSPACE/docs/content/current"
+          jq -nr --arg version "current" '{"versions": [{"name": $version,"branch": $version,"deprecated": false,"isDefault": true}]}' > config.json
+          NEW_PACKAGE_JSON=$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json);
+          NEW_PACKAGE_JSON=$(jq '.scripts."prepare-sanity-data" = "echo Using pre-populated Sanity data"' <<< "$NEW_PACKAGE_JSON");
+          echo "$NEW_PACKAGE_JSON" > package.json;
+          echo "{}" > data/events.json
+          echo '{"bannerButtons":{"second":{"title":"LOG IN","url":"https://teleport.sh"},"first":{"title":"Support","url":"https://goteleport.com/support/"}},"navbarData":{"rightSide":{},"logo":"/favicon.svg","menu":[]}}' > data/navbar.json
 
       - name: Check spelling
-        run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport
+        working-directory: 'docs'
+        run: yarn spellcheck content/current
 
       - name: Lint the docs
         run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint

docs/cspell.json

@@ -2,6 +2,14 @@
   "language": "en",
   "version": "0.2",
   "words": [
+    "aada",
+    "abee",
+    "fffc",
+    "fabfc",
+    "microservices",
+    "configmaps",
+    "genrsa",
+    "displayname",
     "AADUSER",
     "ABCDEFGHIJKL",
     "ADFS",

docs/pages/enroll-resources/application-access/guides/connecting-apps.mdx

@@ -132,10 +132,9 @@ Teleport, you must configure these yourself:
      Service domain, e.g., `*.teleport.example.com`, with the domain name of the
      Teleport Proxy Service.
 
-1. Ensure that your system provisionings TLS certificates for
-   Teleport-registered applications. The method to use depends on how you
-   originally set up TLS for your self-hosted Teleport deployment, and is
-   outside the scope of this guide. 
+1. Ensure that your system provisions TLS certificates for Teleport-registered
+   applications. The method to use depends on how you originally set up TLS for
+   your self-hosted Teleport deployment, and is outside the scope of this guide. 
 
    In general, the same system that provisions TLS certificates signed for the
    web address of the Proxy Service (e.g., `teleport.example.com`) must also

docs/pages/reference/resources.mdx

@@ -126,7 +126,7 @@ When no `kubernetes_resource` is set:
 {/* This table is cursed. Our current docs engine doesn't support HTML tables
 (due to SSR and the rehydration process). We have dto do everything inlined in
 markdown. Some HTML character codes are used to render specific chars like {}
-or to avoid line breaks in the middle fo the YAML. Whitespaces before br tags
+or to avoid line breaks in the middle fo the YAML. Spaces before br tags
 are required.*/}
 
 | Allow rule                                                                                                                                                                                                                                                                | Role v5                                                                                                           | Role v6                                                                                                           | Role v7                                                                                                                                                                                               |