Change documentation platform from Docz to MkDocs with Docoff (#373)

.browserslistrc

@@ -3,4 +3,3 @@
 defaults
 not ie > 1
 not ie_mob > 1
-maintained node versions

.env.dist

@@ -0,0 +1,6 @@
+# Host system port where the live documentation is to be made accessible
+COMPOSE_START_PORT=8000
+
+# Ownership of the files created in the container
+COMPOSE_UID=1000
+COMPOSE_GID=1000

.eslintrc

@@ -6,12 +6,12 @@
     "browser": true,
     "jest": true
   },
+  "ignorePatterns": ["src/docs/_assets/generated"],
   "overrides": [
     {
-      "files": ["**/*.md", "**/*.mdx"],
+      "files": ["**/*.md"],
       "extends": [
-        "plugin:markdown/recommended",
-        "plugin:mdx/recommended"
+        "plugin:markdown/recommended"
       ]
     }
   ],

.github/workflows/build.yml

@@ -0,0 +1,31 @@
+name: Build
+
+on: [ pull_request ]
+
+jobs:
+  build:
+    name: Build distribution CSS and JS
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        # TODO: Add v18 back (#374) once the docs platform is migrated to a non-Gatsby solution (#373).
+        # node: [ 16, 18 ]
+        node: [ 16 ]
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Print Node.js and npm version
+        run: node --version && npm --version
+
+      - name: Install
+        run: npm ci
+
+      - name: Build
+        run: npm run build

.github/workflows/docs.yml

@@ -0,0 +1,36 @@
+name: Docs
+
+on: [ pull_request ]
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    name: Build Docs
+    runs-on: ubuntu-20.04
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - name: Get cache ID
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - name: Restore cache
+        uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+
+      - name: Install MkDocs
+        run: pip install 'mkdocs-material>=9.0.0,<10.0.0'
+
+      - name: Build MkDocs
+        run: mkdocs build

.github/workflows/lint.yml

@@ -0,0 +1,31 @@
+name: Lint
+
+on: [ pull_request ]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-20.04
+    strategy:
+      matrix:
+        # TODO: Add v18 back (#374) once the docs platform is migrated to a non-Gatsby solution (#373).
+        # node: [ 16, 18 ]
+        node: [ 16 ]
+    steps:
+      - name: Clone repository
+        uses: actions/checkout@v3
+
+      - name: Set up Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node }}
+          cache: npm
+
+      - name: Print Node.js and npm version
+        run: node --version && npm --version
+
+      - name: Install
+        run: npm ci
+
+      - name: Test
+        run: npm run lint

.github/workflows/release-management.yml

@@ -23,12 +23,15 @@ jobs:
       - name: Install
         run: npm ci
 
-      - name: Build
-        run: npm run build
+      - name: Lint
+        run: npm run lint
 
       - name: Test
         run: npm test
 
+      - name: Build
+        run: docker compose run --rm node_build_site && docker compose run --rm mkdocs_build_site
+
       - name: Check package.json for version change
         id: check_package_version
         uses: EndBug/version-check@v2
@@ -45,7 +48,7 @@ jobs:
         uses: actions/upload-artifact@v3
         with:
           name: docs
-          path: docs
+          path: site
 
   update_release_draft:
     name: Update release draft

.github/workflows/test.yml

@@ -1,10 +1,10 @@
-name: Build and Run Tests
+name: Test
 
 on: [ pull_request ]
 
 jobs:
-  build_and_test:
-    name: Build and test
+  test:
+    name: Test
     runs-on: ubuntu-20.04
     strategy:
       matrix:
@@ -27,8 +27,5 @@ jobs:
       - name: Install
         run: npm ci
 
-      - name: Build
-        run: npm run build
-
       - name: Test
         run: npm test

.gitignore

@@ -1,6 +1,7 @@
-/.docz
 /dist
-/docs
 /node_modules
-lib-stats.development.html
-lib-stats.html
+/site
+/src/docs/_assets/generated/*
+.env
+statistics.html
+!.gitkeep

.markdownlint.jsonc

@@ -2,9 +2,11 @@
 
 {
   "default": true,
+  "MD033": false, // Allow inline JSX.
+  "MD024": false, // Allow duplicate headings
   "line-length": {
     "code_block_line_length": 120,
-    "tables": false
-  },
-  "no-inline-html": false // Allow inline JSX.
+    "tables": false,
+    "code_blocks": false
+  }
 }

.npmignore

@@ -1,25 +1,29 @@
-/.docz
 /.github
 /.idea
-/docs
+/docker
 /node_modules
-/src/docs/
-/src/gatsby-theme-docz/
+/public
+/site
 /src/**/__tests__
+/src/docs/
+/src/cssCustomProperties.js
+/src/index.md
 /tests
 .browserslistrc
 .editorconfig
+.env
+.env.dist
 .eslintrc
 .gitignore
 .markdownlint.jsonc
 babel.config.js
-doczrc.js
-gatsby-config.js
+CONTRIBUTING.md
+docker-compose.yml
 jest.config.js
-lib-stats.development.html
-lib-stats.html
+mkdocs.yml
 package-lock.json
 postcss.config.js
 RELEASING.md
+statistics.html
 stylelint.config.js
-webpack.config.js
+webpack.config.babel.js