docs: validate with mkdocs (#30735)

Co-authored-by: HonkingGoose <[email protected]>

.eslintignore

@@ -1,5 +1,9 @@
 # don't ever lint node_modules
 node_modules
+
+# don't lint pnpm store
+.pnpm-store
+
 # don't lint build output (make sure it's set to your correct build folder name)
 dist
 # don't lint nyc coverage output
@@ -18,3 +22,8 @@ coverage
 /tools/dist
 /patches
 tmp/
+.venv/
+
+# generated mkdocs files
+tools/mkdocs/docs
+tools/mkdocs/site

.github/workflows/build.yml

@@ -31,6 +31,7 @@ concurrency:
 env:
   DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
   NODE_VERSION: 20
+  PDM_VERSION: 2.17.3 # renovate: datasource=pypi depName=pdm
   DRY_RUN: true
   TEST_LEGACY_DECRYPTION: true
   SPARSE_CHECKOUT: |-
@@ -583,8 +584,20 @@ jobs:
           node-version: ${{ needs.setup-build.outputs.node-version }}
           os: ${{ runner.os }}
 
+      - name: Setup PDM
+        uses: pdm-project/setup-pdm@568ddd69406b30de1774ec0044b73ae06e716aa4 # v4.1
+        with:
+          python-version-file: .python-version
+          version: ${{ env.PDM_VERSION }}
+          cache: true
+
+      - name: Install pdm dependencies
+        run: pdm install
+
       - name: Build
         run: pnpm build:docs
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Test docs
         run: pnpm test:docs
@@ -595,6 +608,9 @@ jobs:
           name: docs
           path: tmp/docs/
 
+      - name: Build mkdocs
+        run: pnpm build:mkdocs --build=false
+
   test-e2e:
     needs: [build]
     runs-on: 'ubuntu-latest'

.gitignore

@@ -27,3 +27,6 @@ test/datasource/nuget/_fixtures/obj
 
 # testing
 /docker-compose.yml
+
+# pdm
+/.pdm-python

.ls-lint.yml

@@ -12,10 +12,14 @@ ignore:
   - .git
   - .github/ISSUE_TEMPLATE
   - .github/pull_request_template.md
+  - .venv
   - CODE_OF_CONDUCT.md
   - dist
   - jest.config.ts
   - node_modules
   - SECURITY.md
   - test/e2e/node_modules
   - tmp
+  - tools/mkdocs/docs
+  - tools/mkdocs/site
+  - tools/mkdocs/.cache

.markdownlint-cli2.jsonc

@@ -7,12 +7,20 @@
     "line-length": false,
     "no-emphasis-as-header": false,
     "no-inline-html": false,
-    "single-h1": false
+    "single-h1": false,
   },
 
   // Define glob expressions to use (only valid at root)
   "globs": ["**/*.md"],
 
   // Define glob expressions to ignore
-  "ignores": ["**/__fixtures__/*", "**/node_modules/**", "./tmp/**/*"]
+  "ignores": [
+    "**/__fixtures__/*",
+    "**/node_modules/**",
+    "tmp/**",
+    "**/.cache/**",
+    ".venv/**",
+    "tools/mkdocs/docs/**",
+    "tools/mkdocs/site/**",
+  ],
 }

.prettierignore

@@ -1,6 +1,7 @@
 # It would be nice to remove this file and use .gitignore instead however we need to add package.json and __fixtures__
 
 /node_modules
+/.pnpm-store
 /config.js
 /coverage
 /dist
@@ -19,3 +20,20 @@ package.json
 /tools/dist
 /patches
 **/tmp/
+/.venv/
+
+pdm.lock
+pnpm-lock.yaml
+
+# Ignore the mkdocs.yml file, as Prettier moves some comments around
+/tools/mkdocs/mkdocs.yml
+
+# Ignore the list of abbreviations, as Prettier messes up the syntax
+/tools/mkdocs/includes/abbreviations.md
+
+# Ignore overrides/main.html because Prettier messes up the formatting
+/tools/mkdocs/overrides/main.html
+
+# mkdocs generated files
+/tools/mkdocs/docs
+/tools/mkdocs/site

.python-version

@@ -0,0 +1 @@
+3.12.4

.vscode/settings.json

@@ -27,5 +27,9 @@
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
     "source.fixAll.eslint": "explicit"
-  }
+  },
+  "yaml.customTags": [
+    "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:materialx.emoji.to_svg"
+  ]
 }

docs/usage/assets/css/style.css

@@ -0,0 +1,10 @@
+.md-header .md-header__button.md-logo {
+  padding: 0;
+}
+.md-header .md-header__button.md-logo img,
+.md-header .md-header__button.md-logo svg {
+  height: 1.5rem;
+}
+.md-typeset a {
+  text-decoration: underline;
+}

package.json

@@ -11,6 +11,7 @@
     "build": "run-s clean 'generate:*' 'compile:*' create-json-schema",
     "build:docker": "ts-node tools/docker.ts",
     "build:docs": "ts-node tools/generate-docs.ts",
+    "build:mkdocs": "ts-node tools/mkdocs.ts",
     "clean": "rimraf dist tmp",
     "clean-cache": "node tools/clean-cache.mjs",
     "compile:ts": "tsc -p tsconfig.app.json",