Add CI guardrails for docs, lint, and search updates

.github/workflows/jekyll.yml

@@ -16,6 +16,46 @@ jobs:
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Block node_modules changes on pull requests
+      if: github.event_name == 'pull_request'
+      run: |
+        BASE_SHA="${{ github.event.pull_request.base.sha }}"
+        HEAD_SHA="${{ github.event.pull_request.head.sha }}"
+        CHANGED_NODE_MODULES="$(git diff --name-only "${BASE_SHA}...${HEAD_SHA}" -- 'node_modules/**')"
+
+        if [ -n "${CHANGED_NODE_MODULES}" ]; then
+          echo "::error title=Blocked path::Pull request includes changes under node_modules/."
+          echo "${CHANGED_NODE_MODULES}"
+          exit 1
+        fi
+
+    - name: Block node_modules changes on pushes
+      if: github.event_name == 'push'
+      run: |
+        BASE_SHA="${{ github.event.before }}"
+        HEAD_SHA="${{ github.sha }}"
+        ZERO_SHA="0000000000000000000000000000000000000000"
+
+        if [ "${BASE_SHA}" = "${ZERO_SHA}" ]; then
+          echo "Initial push detected; skipping node_modules diff guard."
+          exit 0
+        fi
+
+        CHANGED_NODE_MODULES="$(git diff --name-only "${BASE_SHA}...${HEAD_SHA}" -- 'node_modules/**')"
+
+        if [ -n "${CHANGED_NODE_MODULES}" ]; then
+          echo "::error title=Blocked path::Push includes changes under node_modules/."
+          echo "${CHANGED_NODE_MODULES}"
+          exit 1
+        fi
+
+    - name: Verify thesis navigation docs stay in sync
+      run: |
+        chmod +x scripts/check-phd-thesis-nav-docs.sh
+        ./scripts/check-phd-thesis-nav-docs.sh
 
     - name: Set up Ruby
       uses: ruby/setup-ruby@v1

.github/workflows/update-search.yml

@@ -35,42 +35,65 @@ jobs:
           fetch-depth: 0 # Fetch all history for proper git operations
 
       - name: Clone comphy-search repository
+        id: clone-search-repo
         run: |
           GITHUB_ORG="${GITHUB_REPOSITORY%%/*}"
           SEARCH_REPO="${SEARCH_REPO:-comphy-search}"
           echo "Attempting to clone search database from ${GITHUB_ORG}/${SEARCH_REPO}..."
 
           if git clone "https://github.com/${GITHUB_ORG}/${SEARCH_REPO}.git"; then
             mkdir -p assets/js
+            echo "clone_ok=true" >> "${GITHUB_OUTPUT}"
             echo "Search database repository cloned successfully"
           else
+            echo "clone_ok=false" >> "${GITHUB_OUTPUT}"
             echo "Warning: Could not clone ${GITHUB_ORG}/${SEARCH_REPO}"
             echo "Search functionality may be limited. This is expected if the search repository does not exist."
+            echo "::warning title=Search DB clone failed::Could not clone ${GITHUB_ORG}/${SEARCH_REPO}. Search update will be skipped."
+            {
+              echo "### Search DB update skipped"
+              echo "- Clone failed for \`${GITHUB_ORG}/${SEARCH_REPO}\`."
+            } >> "${GITHUB_STEP_SUMMARY}"
             exit 0
           fi
 
       - name: Copy search database
+        id: copy-search-db
+        if: steps.clone-search-repo.outputs.clone_ok == 'true'
         run: |
           SEARCH_REPO="${SEARCH_REPO:-comphy-search}"
+          echo "search_db_available=false" >> "${GITHUB_OUTPUT}"
 
           if [ ! -d "${SEARCH_REPO}" ]; then
             echo "Warning: ${SEARCH_REPO} directory not found (clone may have failed)"
             echo "Search functionality will be limited"
+            echo "::warning title=Search DB directory missing::Directory ${SEARCH_REPO} was not found."
+            {
+              echo "### Search DB update skipped"
+              echo "- Directory \`${SEARCH_REPO}\` was not found after clone."
+            } >> "${GITHUB_STEP_SUMMARY}"
             exit 0
           fi
 
           mkdir -p assets/js
 
           if [ -f "${SEARCH_REPO}/search_db.json" ]; then
             cp "${SEARCH_REPO}/search_db.json" assets/js/search_db.json
+            echo "search_db_available=true" >> "${GITHUB_OUTPUT}"
             echo "Search database copied successfully"
           else
             echo "Warning: search_db.json not found in ${SEARCH_REPO}"
             echo "Search functionality will be limited"
+            echo "::warning title=search_db.json missing::No search_db.json found in ${SEARCH_REPO}."
+            {
+              echo "### Search DB update skipped"
+              echo "- Missing \`${SEARCH_REPO}/search_db.json\`."
+            } >> "${GITHUB_STEP_SUMMARY}"
             exit 0
           fi
 
       - name: Commit and push changes
+        if: steps.copy-search-db.outputs.search_db_available == 'true'
         run: |
           git config --local user.name 'comphy-search-updater[bot]'
           git config --local user.email "${{ env.APP_BOT_USER_ID }}+comphy-search-updater[bot]@users.noreply.github.com"

.gitignore

@@ -1,3 +1,4 @@
+.comphy
 _site/
 .sass-cache/
 .jekyll-cache/

.markdownlint-cli2.jsonc

@@ -0,0 +1,6 @@
+{
+  "config": {
+    "MD034": true,
+  },
+  "ignores": ["node_modules/**", "assets/css/academicons-1.7.0/README.md"],
+}

AGENTS.md

@@ -82,6 +82,17 @@ The following pages redirect to the CoMPhy Lab website:
 - **\_layouts/default.html**: Base template for all pages
 - **Gemfile**: Ruby dependencies including Jekyll 4.3.2 and various
   plugins
+- **MathJax**: Loaded from the local vendored asset first
+  (`/assets/js/mathjax/tex-svg.js`) for offline and archival reproducibility,
+  with a pinned jsDelivr fallback
+  (`https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js`, with SRI)
+  for consistent behavior when online (requires CDN availability).
+
+### Math Authoring Policy
+
+- Inline math supports both `\(...\)` and `$...$`.
+- Escape literal dollar signs in content as `\$` to prevent accidental math
+  parsing.
 
 ### Content Management
 

README.md

@@ -55,7 +55,7 @@ The personal website for Vatsal Sanjay, hosted at [comphy-lab.org/vatsalsy](http
    ```bash
    bundle exec jekyll serve
    ```
-   - Visit http://localhost:4000 in the browser
+   - Visit <http://localhost:4000> in the browser
    - Changes in source files trigger automatic rebuilds
 
 4. **Deployment**

_layouts/default.html

@@ -28,14 +28,19 @@
   <script>
     window.MathJax = {
       tex: {
+        // Keep $...$ support for existing content; escape literal currency as \$.
         inlineMath: [['\\(', '\\)'], ['$', '$']]
       },
       svg: {
         fontCache: 'global'
       }
     };
   </script>
-  <script defer src="{{ site.baseurl }}/assets/js/mathjax/tex-svg.js"></script>
+  <script
+    defer
+    src="{{ site.baseurl }}/assets/js/mathjax/tex-svg.js"
+    onerror="this.onerror=null;this.crossOrigin='anonymous';this.integrity='sha384-KKWa9jJ1MZvssLeOoXG6FiOAZfAgmzsIIfw8BXwI9+kYm0lPCbC6yTQPBC00F1/L';this.src='https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg.js';"
+  ></script>
 
   <script>
     document.documentElement.classList.remove('no-js');

scripts/check-phd-thesis-nav-docs.sh

@@ -0,0 +1,45 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+LAYOUT_FILE="${REPO_ROOT}/_layouts/default.html"
+DOC_FILE="${REPO_ROOT}/AGENTS.md"
+
+NAV_LINK='href="{{ site.baseurl }}/phd-thesis/"'
+DOC_PHRASE="This page is included in the main navigation menu"
+
+if [[ ! -f "${LAYOUT_FILE}" ]]; then
+  echo "Missing layout file: ${LAYOUT_FILE}"
+  exit 1
+fi
+
+if [[ ! -f "${DOC_FILE}" ]]; then
+  echo "Missing docs file: ${DOC_FILE}"
+  exit 1
+fi
+
+nav_present=0
+doc_phrase_present=0
+
+if grep -Fq "${NAV_LINK}" "${LAYOUT_FILE}"; then
+  nav_present=1
+fi
+
+if grep -Fq "${DOC_PHRASE}" "${DOC_FILE}"; then
+  doc_phrase_present=1
+fi
+
+if [[ ${nav_present} -eq 1 && ${doc_phrase_present} -eq 0 ]]; then
+  echo "PhD thesis nav link exists but docs are stale."
+  echo "Update AGENTS.md to mention thesis page is in main navigation."
+  exit 1
+fi
+
+if [[ ${nav_present} -eq 0 && ${doc_phrase_present} -eq 1 ]]; then
+  echo "Docs mention thesis page in main navigation but nav link is missing."
+  echo "Update AGENTS.md or restore nav link in _layouts/default.html."
+  exit 1
+fi
+
+echo "PhD thesis nav/docs check passed."