Stuartferguson00 · ferozmay · May 24, 2026 · May 24, 2026 · May 24, 2026
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -3,6 +3,7 @@ name: Build & Deploy Docs
 on:
   push:
     branches: [ main ]
+  pull_request:
   workflow_dispatch:
 
 permissions:
@@ -12,7 +13,7 @@ permissions:
 
 concurrency:
   group: "pages"
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 jobs:
   build:
@@ -22,23 +23,24 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: "3.13"
 
       - name: Install docs dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r docs/requirements.txt
 
-      - name: Build Sphinx HTML
-        run: |
-          python -m sphinx -b html docs/source docs/build/html
+      - name: Build site (strict)
+        run: mkdocs build --strict
 
       - name: Upload artifact
+        if: github.ref == 'refs/heads/main'
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/build/html
+          path: site
 
   deploy:
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     needs: build
     environment:
@@ -47,4 +49,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/source/authors.md → docs/authors.md b/docs/source/authors.md → docs/authors.md
diff --git a/docs/source/coarse-graining.md → docs/coarse-graining.md b/docs/source/coarse-graining.md → docs/coarse-graining.md
diff --git a/docs/source/constraints.md → docs/constraints.md b/docs/source/constraints.md → docs/constraints.md
diff --git a/docs/source/energy-model.md → docs/energy-model.md b/docs/source/energy-model.md → docs/energy-model.md
@@ -53,11 +53,11 @@ Q = np.array([                         # quadratic coefficients b_ij (symmetric,
 model = EnergyModel(n=n, couplings=[q, Q], name="my_qubo", model_type="binary")
 ``` -->
 
-```{note}
-Provide the quadratic term as a **full symmetric matrix with a zero diagonal** (not
-upper-triangular): QeMCMC sums over all $i, j$ and halves the result, giving the $\sum_{i<j}$
-above. Linear coefficients always go in the separate 1D array, never on the diagonal.
-```
+!!! note
+    Provide the quadratic term as a **full symmetric matrix with a zero diagonal** (not
+    upper-triangular): QeMCMC sums over all $i, j$ and halves the result, giving the
+    $\sum_{i<j}$ above. Linear coefficients always go in the separate 1D array, never on
+    the diagonal.
 
 ## Sign convention
 

diff --git a/docs/favicon.svg b/docs/favicon.svg
diff --git a/docs/source/getting-started.md → docs/getting-started.md b/docs/source/getting-started.md → docs/getting-started.md
diff --git a/docs/source/github.md → docs/github.md b/docs/source/github.md → docs/github.md
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,4 @@
+{%
+   include-markdown "../README.md"
+   rewrite-relative-urls=false
+%}
diff --git a/docs/javascripts/mathjax.js b/docs/javascripts/mathjax.js
@@ -0,0 +1,19 @@
+window.MathJax = {
+  tex: {
+    inlineMath: [["\\(", "\\)"]],
+    displayMath: [["\\[", "\\]"]],
+    processEscapes: true,
+    processEnvironments: true
+  },
+  options: {
+    ignoreHtmlClass: ".*|",
+    processHtmlClass: "arithmatex"
+  }
+};
+
+document$.subscribe(() => {
+  MathJax.startup.output.clearCache();
+  MathJax.typesetClear();
+  MathJax.texReset();
+  MathJax.typesetPromise();
+});
diff --git a/docs/source/license.md → docs/license.md b/docs/source/license.md → docs/license.md
diff --git a/docs/source/_static/logo-qsl.jpeg → docs/logo-qsl.jpeg b/docs/source/_static/logo-qsl.jpeg → docs/logo-qsl.jpeg
diff --git a/docs/make.bat b/docs/make.bat
diff --git a/docs/source/quickstart.md → docs/quickstart.md b/docs/source/quickstart.md → docs/quickstart.md
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,45 +1,10 @@
-
-
-autoapi==2.0.1
-sphinx-autoapi==3.7.0
-sphinx>=8
-sphinx-copybutton==0.5.2
-accessible-pygments==0.0.5
-alabaster==1.0.0
-babel==2.17.0
-beautifulsoup4==4.14.2
-certifi==2025.10.5
-charset-normalizer==3.4.4
-commonmark==0.9.1
-docutils==0.21.2
-furo==2025.9.25
-idna==3.11
-imagesize==1.4.1
-Jinja2==3.1.6
-linkify-it-py==2.0.3
-markdown-it-py==4.0.0
-MarkupSafe==3.0.3
-mdit-py-plugins==0.5.0
-mdurl==0.1.2
-myst-parser==5.0.0
-packaging==25.0
-Pygments==2.19.2
-PyYAML==6.0.3
-recommonmark==0.7.1
-requests==2.32.5
-roman-numerals-py==3.1.0
-snowballstemmer==3.0.1
-soupsieve==2.8
-Sphinx==8.2.3
-sphinx-autodoc-typehints==3.5.2
-sphinx-rtd-theme==3.0.2
-sphinxcontrib-applehelp==2.0.0
-sphinxcontrib-devhelp==2.0.0
-sphinxcontrib-htmlhelp==2.1.0
-sphinxcontrib-jquery==4.1
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==2.0.0
-sphinxcontrib-serializinghtml==2.0.0
-typing_extensions==4.15.0
-uc-micro-py==1.0.3
-urllib3==2.5.0
+# Documentation toolchain (MkDocs + Material).
+# Static analysis only — no need to install the package or its heavy deps.
+mkdocs>=1.6
+mkdocs-material>=9.5
+mkdocstrings[python]>=0.26
+mkdocs-gen-files>=0.5
+mkdocs-literate-nav>=0.6
+mkdocs-section-index>=0.3
+mkdocs-include-markdown-plugin>=6.0
+black>=24.0   # formats the auto-generated API signatures
diff --git a/docs/source/conf.py b/docs/source/conf.py
diff --git a/docs/source/index.md b/docs/source/index.md