feat(docussaurus): upgrade Docussaurus and document development procedures

.github/workflows/config/markdown.links.config.json

@@ -0,0 +1,10 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?(/.*)?$"
+    },
+    {
+      "pattern": "^https?://controller\\.url\\.sample(:\\d+)?(/.*)?$"
+    }
+  ]
+}

.github/workflows/config/markdown_lint.json

@@ -0,0 +1,58 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "^(?!http).*"
+    },
+    {
+      "pattern": ".*%2F*"
+    },
+    {
+      "pattern": ".*127.0.0.1.*"
+    },
+    {
+      "pattern" : ".*localhost.*"
+    },
+    {
+      "pattern": "^https://controller.url.sample:9443"
+    },
+    {
+      "pattern": "^https://nms.yourdomain.com"
+    },
+    {
+      "pattern" : "^https://your-org.nms.yourdomain.com"
+    },
+    {
+      "pattern" : "https://magma.github.io/magma/docs/orc8r/rds_upgrade#logs-and-validation"
+    },
+    {
+      "pattern" : "https://github.com/fbcinternal/ens_magma/tree/master/spirent_automation"
+    },
+    {
+      "pattern" : "https://github.com/magma/ci-infra/blob/master/bazel/remote_caching/Readme.md"
+    },
+    {
+      "pattern" : "https://github.com/magma/security/issues"
+    },
+    {
+      "pattern" : "https://github.com/dysinger/basebox"
+    },
+    {
+      "pattern" : "https://docs.virtlet.cloud/user-guide/real-cluster/"
+    },
+    {
+      "pattern" : "^https://www.etsi.org.*pdf"
+    },
+    {
+      "pattern" : "https://core.ac.uk/download/pdf/322886318.pdf"
+    },
+    {
+      "pattern" : "http://automation.fbmagma.ninja/"
+    },
+    {
+      "pattern" : "http://ens-spirent-test-summary.com.s3-us-west-1.amazonaws.com/sanity/hilsanitypass.svg"
+    },
+    {
+      "pattern" : "https://fb.quip.com/4tmUAtlox4Oy"
+    }
+  ]
+}

.github/workflows/docs-fix.yml

@@ -0,0 +1,60 @@
+# Copyright 2022 The Magma Authors.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# owner: @magma/approvers-infra
+# purpose: Fixes the documentation if any issue is found during tests
+# remediation: 
+
+name: Docs Fix (Triggered on Check Failure)
+
+on:
+  workflow_run:
+    workflows: ["Docs Check"]
+    types:
+      - completed
+
+jobs:
+  only_if_failed:
+    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Setup Python (if needed)
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.8'
+
+      - name: Install deps
+        run: yarn install --frozen-lockfile
+
+      - name: Run precommit fix
+        run: make -C readmes precommit_fix
+
+      - name: Show diff after fix
+        run: git diff --color
+
+      - name: Upload patch
+        run: |
+          git diff > docs_fixes.patch
+        continue-on-error: true
+
+      - name: Upload auto-fix patch
+        uses: actions/upload-artifact@v4
+        with:
+          name: auto-fix-patch
+          path: docs_fixes.patch

.github/workflows/docs-test.yml

@@ -0,0 +1,113 @@
+# Copyright 2022 The Magma Authors.
+#
+# This source code is licensed under the BSD-style license found in the
+# LICENSE file in the root directory of this source tree.
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# owner: @magma/approvers-infra
+# purpose: Check the documentation changes for issues and formatting errors
+# remediation: 
+---
+name: Docs Check
+
+on:
+  pull_request:
+    branches: [ main ]
+  push:
+    branches: [ main ]
+
+jobs:
+  docusaurus-test:
+    name: Docusaurus Build & Log
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: |
+          cd docusaurus/
+          yarn install --frozen-lockfile
+
+      - name: Build and test Docusaurus
+        run: |
+          cd docusaurus/
+          yarn test
+
+      - name: Verify build output
+        run: |
+          cd docusaurus/
+          test -d build && echo "✅ Build successful"
+
+  markdown-lint:
+    name: Markdown Format Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli
+      - name: Run markdownlint
+        run: markdownlint "docs/**/*.md" "readmes/**/*.md"
+
+  translation-consistency:
+    name: Translation Consistency Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Grant execute permissions and convert script file
+        run: |
+          chmod +x ./.github/workflows/scripts/check_translations.sh
+      - name: Check Translation Consistency
+        run: |
+          ./.github/workflows/scripts/check_translations.sh --debug
+        shell: bash
+
+  id-filename-sync:
+    name: Docusaurus ID & Filename Sync
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Grant execute permissions to scripts and convert script file
+        run: |
+          chmod +x ./.github/workflows/scripts/check_id_matches_filename.sh
+      - name: Check ID matches filename
+        run: |
+          ./.github/workflows/scripts/check_id_matches_filename.sh --debug
+
+  check-symlinks:
+    name: Broken Symlinks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check for broken symlinks in docusaurus/
+        working-directory: ${{ github.workspace }}/docusaurus
+        run: |
+          BROKEN=$(find . -xtype l)
+          if [ -n "$BROKEN" ]; then
+            echo "❌ Broken symlinks found:"
+            echo "$BROKEN"
+            exit 1
+          else
+            echo "✅ No broken symlinks found in ./docusaurus."
+          fi
+
+  markdown-link-check:
+    name: Markdown URL Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          config-file: '.github/workflows/config/markdown.links.config.json'
+          folder-path: './docusaurus/docs'