Render docs with DocumenterVitePress

.gitignore

@@ -4,3 +4,9 @@ Manifest.toml
 .DS_Store
 **/dev/
 benchmark/results
+
+# DocumenterVitepress / Node build artifacts
+**/node_modules/
+**/.vitepress/cache/
+**/.vitepress/dist/
+package-lock.json

Project.toml

@@ -4,7 +4,7 @@ version = "0.13.13"
 authors = "Lukas Devos, Maarten Van Damme and contributors"
 
 [workspace]
-projects = ["test", "docs"]
+projects = ["test", "docs", "examples"]
 
 [deps]
 Accessors = "7d9f7c33-5ae7-4f3b-8dc6-eff91059b697"

docs/.gitignore

@@ -0,0 +1,4 @@
+build/
+node_modules/
+package-lock.json
+Manifest.toml

docs/Project.toml

@@ -4,6 +4,7 @@ name = "MPSKitDocs"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 KrylovKit = "0b1a1467-8014-51b9-945f-bf0ae24f4b77"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 MPSKit = "bb1c41ca-d63c-52ed-829e-0820dda26502"
@@ -18,5 +19,6 @@ TensorOperations = "6aa20fa7-93e2-5fca-9bc0-fbd0db3c71a2"
 MPSKit = {path = ".."}
 
 [compat]
-Documenter = "1.0"
+Documenter = "1.11"
 DocumenterInterLinks = "1"
+DocumenterVitepress = "0.3"

docs/make.jl

@@ -8,6 +8,7 @@ end
 
 using MPSKit
 using Documenter
+using DocumenterVitepress
 using DocumenterCitations
 using DocumenterInterLinks
 
@@ -37,23 +38,12 @@ links = InterLinks(
 # include MPSKit in all doctests
 DocMeta.setdocmeta!(MPSKit, :DocTestSetup, :(using MPSKit, TensorKit); recursive = true)
 
-mathengine = MathJax3(
-    Dict(
-        :loader => Dict("load" => ["[tex]/physics"]),
-        :tex => Dict(
-            "inlineMath" => [["\$", "\$"], ["\\(", "\\)"]],
-            "tags" => "ams",
-            "packages" => ["base", "ams", "autoload", "physics"]
-        )
-    )
-)
 makedocs(;
     sitename = "MPSKit.jl",
-    format = Documenter.HTML(;
-        prettyurls = true,
-        mathengine,
-        assets = ["assets/custom.css"],
-        size_threshold = 1024000,
+    format = DocumenterVitepress.MarkdownVitepress(;
+        repo = "github.com/QuantumKitHub/MPSKit.jl",
+        devbranch = "main",
+        devurl = "dev",
     ),
     pages = [
         "Home" => "index.md",
@@ -76,4 +66,10 @@ makedocs(;
     plugins = [bib, links]
 )
 
-deploydocs(; repo = "github.com/QuantumKitHub/MPSKit.jl.git", push_preview = true)
+DocumenterVitepress.deploydocs(;
+    repo = "github.com/QuantumKitHub/MPSKit.jl.git",
+    target = joinpath(@__DIR__, "build"),
+    branch = "gh-pages",
+    devbranch = "main",
+    push_preview = true,
+)

docs/package.json

@@ -0,0 +1,20 @@
+{
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "@types/markdown-it-footnote": "^3.0.4"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev build/.documenter",
+    "docs:build": "vitepress build build/.documenter",
+    "docs:preview": "vitepress preview build/.documenter"
+  },
+  "dependencies": {
+    "@nolebase/vitepress-plugin-enhanced-readabilities": "^2.18.2",
+    "@mdit/plugin-mathjax": "^0.26.1",
+    "@mdit/plugin-tex": "^0.24.1",
+    "markdown-it-footnote": "^4.0.0",
+    "markdown-it": "^14.1.0",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-tabs": "^0.8.0"
+  }
+}

docs/src/.vitepress/theme/custom.css

@@ -0,0 +1,21 @@
+/* ===== MPSKit branding ===== */
+/* Accent color matching the (green) MPSKit logo in light mode.
+   Dark mode already uses the green palette defined by the DVP template. */
+:root {
+  --vp-c-brand: var(--julia-green);
+  --vp-c-brand-1: #389826;
+  --vp-c-brand-2: #2f8420;
+  --vp-c-brand-3: #277018;
+  --vp-c-brand-light: #389826;
+}
+
+/* ===== Color-invertible diagrams =====
+   The manual embeds line-drawing diagrams (black on transparent) via
+   `@raw html` <img class="color-invertible">. Legible on a light background
+   as-is; invert them in dark mode so they read as light-on-dark. */
+.color-invertible {
+  transition: filter 0.2s ease;
+}
+.dark .color-invertible {
+  filter: invert(1) hue-rotate(180deg);
+}

docs/src/.vitepress/theme/index.ts

@@ -0,0 +1,44 @@
+// .vitepress/theme/index.ts
+import { h } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import type { Theme as ThemeConfig } from 'vitepress'
+import 'virtual:mathjax-styles.css';
+
+import { 
+  NolebaseEnhancedReadabilitiesMenu, 
+  NolebaseEnhancedReadabilitiesScreenMenu, 
+} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'
+
+import VersionPicker from "@/VersionPicker.vue"
+import AuthorBadge from '@/AuthorBadge.vue'
+import Authors from '@/Authors.vue'
+import SidebarDrawerToggle from '@/SidebarDrawerToggle.vue'
+
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+
+import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'
+import './style.css' // template default, auto-supplied to the build by DVP
+import './docstrings.css' // template default, auto-supplied to the build by DVP
+import './custom.css' // MPSKit customizations (this repo)
+
+export const Theme: ThemeConfig = {
+  extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      'nav-bar-content-after': () => [
+        h(NolebaseEnhancedReadabilitiesMenu), // Enhanced Readabilities menu
+      ],
+      // A enhanced readabilities menu for narrower screens (usually smaller than iPad Mini)
+      'nav-screen-content-after': () => h(NolebaseEnhancedReadabilitiesScreenMenu),
+      // Sidebar drawer toggle button (to the left of search bar)
+      'nav-bar-content-before': () => h(SidebarDrawerToggle),
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    enhanceAppWithTabs(app);
+    app.component('VersionPicker', VersionPicker);
+    app.component('AuthorBadge', AuthorBadge)
+    app.component('Authors', Authors)
+  }
+}
+export default Theme

docs/src/examples/classic2d/1.hard-hexagon/main.ipynb

@@ -2,6 +2,7 @@
  "cells": [
   {
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "# The Hard Hexagon model\n",
     "\n",
@@ -12,31 +13,32 @@
     "This model is known to have central charge 0.8, and has very peculiar non-local (anyonic) symmetries.\n",
     "Because TensorKit supports anyonic symmetries, so does MPSKit.\n",
     "To follow the tutorial you need the following packages."
-   ],
-   "metadata": {}
+   ]
   },
   {
-   "outputs": [],
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "using MPSKit, MPSKitModels, TensorKit, Plots, Polynomials"
-   ],
-   "metadata": {},
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "The [hard hexagon model](https://en.wikipedia.org/wiki/Hard_hexagon_model) is a 2-dimensional lattice model of a gas, where particles are allowed to be on the vertices of a triangular lattice, but no two particles may be adjacent.\n",
     "This can be encoded in a transfer matrix with a local MPO tensor using anyonic symmetries, and the resulting MPO has been implemented in MPSKitModels.\n",
     "\n",
     "In order to use these anyonic symmetries, we need to generalise the notion of the bond dimension and define how it interacts with the symmetry. Thus, we implement away of converting integers to symmetric spaces of the given dimension, which provides a crude guess for how the final MPS would distribute its Schmidt spectrum."
-   ],
-   "metadata": {}
+   ]
   },
   {
-   "outputs": [],
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "mpo = hard_hexagon()\n",
     "P = physicalspace(mpo, 1)\n",
@@ -46,25 +48,25 @@
     "end\n",
     "\n",
     "@assert isapprox(dim(virtual_space(100)), 100; atol = 3)"
-   ],
-   "metadata": {},
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "## The leading boundary\n",
     "\n",
     "One way to study statistical mechanics in infinite systems with tensor networks is by approximating the dominant eigenvector of the transfer matrix by an MPS.\n",
     "This dominant eigenvector contains a lot of hidden information.\n",
     "For example, the free energy can be extracted by computing the expectation value of the mpo.\n",
     "Additionally, we can compute the entanglement entropy as well as the correlation length of the state:"
-   ],
-   "metadata": {}
+   ]
   },
   {
-   "outputs": [],
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "D = 10\n",
     "V = virtual_space(D)\n",
@@ -77,25 +79,25 @@
     "S = real(first(entropy(ψ)))\n",
     "ξ = correlation_length(ψ)\n",
     "println(\"F = $F\\tS = $S\\tξ = $ξ\")"
-   ],
-   "metadata": {},
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "## The scaling hypothesis\n",
     "\n",
     "The dominant eigenvector is of course only an approximation. The finite bond dimension enforces a finite correlation length, which effectively introduces a length scale in the system. This can be exploited to formulate a scaling hypothesis [pollmann2009](@cite), which in turn allows to extract the central charge.\n",
     "\n",
     "First we need to know the entropy and correlation length at a bunch of different bond dimensions. Our approach will be to re-use the previous approximated dominant eigenvector, and then expanding its bond dimension and re-running VUMPS.\n",
     "According to the scaling hypothesis we should have $S \\propto \\frac{c}{6} log(ξ)$. Therefore we should find $c$ using"
-   ],
-   "metadata": {}
+   ]
   },
   {
-   "outputs": [],
    "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
    "source": [
     "function scaling_simulations(\n",
     "        ψ₀, mpo, Ds; verbosity = 0, tol = 1.0e-6,\n",
@@ -127,33 +129,31 @@
     "p = plot(; xlabel = \"logarithmic correlation length\", ylabel = \"entanglement entropy\")\n",
     "p = plot(log.(ξs), Ss; seriestype = :scatter, label = nothing)\n",
     "plot!(p, ξ -> f(ξ) / 6; label = \"fit\")"
-   ],
-   "metadata": {},
-   "execution_count": null
+   ]
   },
   {
    "cell_type": "markdown",
+   "metadata": {},
    "source": [
     "---\n",
     "\n",
     "*This notebook was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*"
-   ],
-   "metadata": {}
+   ]
   }
  ],
- "nbformat_minor": 3,
  "metadata": {
+  "kernelspec": {
+   "display_name": "Julia 1.12.6",
+   "language": "julia",
+   "name": "julia-1.12"
+  },
   "language_info": {
    "file_extension": ".jl",
    "mimetype": "application/julia",
    "name": "julia",
-   "version": "1.12.4"
-  },
-  "kernelspec": {
-   "name": "julia-1.12",
-   "display_name": "Julia 1.12.4",
-   "language": "julia"
+   "version": "1.12.6"
   }
  },
- "nbformat": 4
+ "nbformat": 4,
+ "nbformat_minor": 3
 }