Add IDF Monaco editor, schema-driven field metadata pills, and TOC/math fixes

.claude/launch.json

@@ -0,0 +1,35 @@
+{
+  "version": "0.0.1",
+  "configurations": [
+    {
+      "name": "zensical-dev",
+      "runtimeExecutable": "bash",
+      "runtimeArgs": [
+        "-c",
+        "cd build/v25.2 && uv run zensical serve -a localhost:$PORT"
+      ],
+      "port": 8000,
+      "autoPort": true
+    },
+    {
+      "name": "dist-server",
+      "runtimeExecutable": "bash",
+      "runtimeArgs": [
+        "-c",
+        "uv run python -m http.server $PORT --directory dist"
+      ],
+      "port": 8003,
+      "autoPort": true
+    },
+    {
+      "name": "idf-editor-dev",
+      "runtimeExecutable": "npm",
+      "runtimeArgs": [
+        "run",
+        "dev"
+      ],
+      "cwd": "idf-editor",
+      "port": 5173
+    }
+  ]
+}

.github/workflows/convert-docs.yml

@@ -75,26 +75,38 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y pandoc
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: idf-editor/package-lock.json
+
+      - name: Build IDF editor bundle
+        run: |
+          cd idf-editor && npm ci --silent && npm run build
+          cp dist/idf-editor.js dist/idf-editor.css ../scripts/assets/
+
+      - name: Compute short version
+        id: short
+        run: |
+          SHORT=$(uv run python -c "from scripts.config import version_to_short; print(version_to_short('${{ matrix.version }}'))")
+          echo "version_short=${SHORT}" >> "$GITHUB_OUTPUT"
+
       - name: Compute cache key
         id: cache-key
         run: |
-          SCRIPTS_HASH=$(find scripts/ -type f -name '*.py' -o -name '*.lua' | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)
+          SCRIPTS_HASH=$(find scripts/ idf-editor/src/ -type f \( -name '*.py' -o -name '*.lua' -o -name '*.ts' -o -name '*.css' \) | sort | xargs sha256sum | sha256sum | cut -d' ' -f1)
           echo "key=docs-${{ matrix.version }}-${SCRIPTS_HASH}" >> "$GITHUB_OUTPUT"
 
       - name: Cache built version
         id: cache
         if: ${{ !inputs.force_rebuild }}
         uses: actions/cache@v4
         with:
-          path: build/${{ matrix.version_short }}
+          path: build/${{ steps.short.outputs.version_short }}
           key: ${{ steps.cache-key.outputs.key }}
 
-      - name: Compute short version
-        id: short
-        run: |
-          SHORT=$(uv run python -c "from scripts.config import version_to_short; print(version_to_short('${{ matrix.version }}'))")
-          echo "version_short=${SHORT}" >> "$GITHUB_OUTPUT"
-
       - name: Clone EnergyPlus source (sparse, doc/ only)
         if: steps.cache.outputs.cache-hit != 'true'
         run: |

.github/workflows/pr-docs-preview.yml

@@ -34,6 +34,18 @@ jobs:
           sudo apt-get update
           sudo apt-get install -y pandoc
 
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: idf-editor/package-lock.json
+
+      - name: Build IDF editor bundle
+        run: |
+          cd idf-editor && npm ci --silent && npm run build
+          cp dist/idf-editor.js dist/idf-editor.css ../scripts/assets/
+
       - name: Determine latest version
         id: version
         run: |

.gitignore

@@ -28,5 +28,9 @@ __pycache__/
 .DS_Store
 Thumbs.db
 
+# IDF editor build artifacts
+idf-editor/dist/
+idf-editor/node_modules/
+
 # Pre-commit cache
 .cache

CLAUDE.md

@@ -135,6 +135,27 @@ All workflows are in `.github/workflows/`:
 
 A reusable action at `.github/actions/setup-python-env/action.yml` handles Python + uv setup.
 
+## IDF Editor (Monaco) Development
+
+The `idf-editor/` directory contains a TypeScript/Vite project that builds a browser-side Monaco editor bundle for IDF code blocks. When making CSS or JS changes to the editor:
+
+1. **Edit source** in `idf-editor/src/` (e.g., `editor-manager.ts`, `idf-editor.css`)
+2. **Build the bundle:** `cd idf-editor && npm run build`
+3. **Copy to assets:** `cp idf-editor/dist/idf-editor.{js,css} scripts/assets/`
+4. **Rebuild the docs:** `make convert VERSION=v25.2.0` (this copies `scripts/assets/` into the build output)
+
+For iterating quickly without a full `make convert`, you can copy assets directly into the build output and rebuild Zensical:
+
+```bash
+cp scripts/assets/idf-editor.{js,css} build/v25.2/docs/assets/
+cd build/v25.2 && uv run zensical build --clean
+```
+
+**Important:** Always use `--clean` (or delete `build/vXX.X/.cache/`) when:
+- Adding or changing a Pygments lexer (e.g., the IDF lexer that produces `language-idf` CSS classes)
+- Changing code block language detection
+- Zensical caches rendered HTML and won't pick up new lexer registrations without clearing the cache
+
 ## Conventions
 
 - All Python code is formatted and linted by Ruff. Run `make check` to validate.

Makefile

@@ -41,8 +41,15 @@ serve: ## Serve the full multi-version site from dist/
 	@echo "Serving full site from dist/ on http://localhost:8003"
 	@uv run python -m http.server 8003 --directory dist
 
+.PHONY: build-editor
+build-editor: ## Build the IDF Monaco editor bundle
+	@echo "Building IDF editor bundle..."
+	@cd idf-editor && npm ci --silent && npm run build
+	@cp idf-editor/dist/idf-editor.js idf-editor/dist/idf-editor.css scripts/assets/
+	@echo "IDF editor bundle built and copied to scripts/assets/"
+
 .PHONY: convert
-convert: ## Convert a single EnergyPlus version (usage: make convert VERSION=v25.2.0)
+convert: build-editor ## Convert a single EnergyPlus version (usage: make convert VERSION=v25.2.0)
 	@if [ -z "$(VERSION)" ]; then echo "Usage: make convert VERSION=v25.2.0"; exit 1; fi
 	@echo "Converting EnergyPlus $(VERSION)..."
 	@mkdir -p build/sources