Using DocumenterVitePress as new documentation site

.gitignore

@@ -5,4 +5,15 @@
 .DS_Store
 docs/Manifest.toml
 test/Manifest.toml
-docs/build/
+docs/build/
+
+# DocumenterVitepress:
+docs/src/.vitepress/cache
+docs/src/.vitepress/dist
+docs/Manifest.toml
+docs/.vscode
+docs/node_modules
+docs/.vitepress/cache
+docs/.vitepress/dist
+docs/.DS_Store
+docs/package-lock.json

docs/Project.toml

@@ -3,6 +3,7 @@ CSV = "336ed68f-0bac-5ca0-87d4-7b16caf5d00b"
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterVitepress = "4710194d-e776-4893-9690-8d956a29c365"
 MultiScaleTreeGraph = "dd4a991b-8a45-4075-bede-262ee62d5583"
 PlantMeteo = "4630fe09-e0fb-4da5-a846-781cb73437b6"
 PlantSimEngine = "9a576370-710b-4269-adf9-4f603a9c6423"

docs/make.jl

@@ -1,7 +1,7 @@
 using PlantSimEngine
 using PlantMeteo
 using DataFrames, CSV
-using Documenter
+using Documenter, DocumenterVitepress
 using CairoMakie
 
 DocMeta.setdocmeta!(PlantSimEngine, :DocTestSetup, :(using PlantSimEngine, PlantMeteo, DataFrames, CSV, CairoMakie); recursive=true)
@@ -11,12 +11,12 @@ makedocs(;
     authors="Rémi Vezy <[email protected]> and contributors",
     repo=Documenter.Remotes.GitHub("VirtualPlantLab", "PlantSimEngine.jl"),
     sitename="PlantSimEngine.jl",
-    format=Documenter.HTML(;
-        prettyurls=get(ENV, "CI", "false") == "true",
-        canonical="https://VirtualPlantLab.github.io/PlantSimEngine.jl",
-        edit_link="main",
-        assets=String[],
-        size_threshold=300000
+    format=DocumenterVitepress.MarkdownVitepress(;
+        deploy_url="https://VirtualPlantLab.github.io/PlantSimEngine.jl",
+        repo="github.com/VirtualPlantLab/PlantSimEngine.jl",
+        devbranch="main",
+        devurl="dev",
+        # build_vitepress=false
     ),
     pages=[
         "Home" => "index.md",
@@ -37,12 +37,13 @@ makedocs(;
             ],
             "Modelers" => "./model_coupling/model_coupling_modeler.md",
         ],
-        "FAQ" => ["./FAQ/translate_a_model.md"],
+        "FAQ" => ["Translate a model" => "./FAQ/translate_a_model.md"],
         "API" => "API.md",
     ]
 )
 
 deploydocs(;
     repo="github.com/VirtualPlantLab/PlantSimEngine.jl.git",
-    devbranch="main"
+    devbranch="main",
+    push_preview=true, # Visit https://VirtualPlantLab.github.io/PlantSimEngine.jl/previews/PR## to visualize the preview
 )

docs/package.json

@@ -0,0 +1,17 @@
+{
+  "devDependencies": {
+    "markdown-it": "^14.1.0",
+    "markdown-it-mathjax3": "^4.3.2",
+    "vitepress": "^1.0.2",
+    "vitepress-plugin-tabs": "^0.5.0"
+  },
+  "scripts": {
+    "docs:dev": "vitepress dev build/.documenter",
+    "docs:build": "vitepress build build/.documenter",
+    "docs:preview": "vitepress preview build/.documenter"
+  },
+  "dependencies": {
+    "@shikijs/transformers": "^1.1.7",
+    "markdown-it-footnote": "^4.0.0"
+  }
+}

docs/src/.vitepress/config.mts

@@ -0,0 +1,57 @@
+import { defineConfig } from 'vitepress'
+import { tabsMarkdownPlugin } from 'vitepress-plugin-tabs'
+import mathjax3 from "markdown-it-mathjax3";
+import footnote from "markdown-it-footnote";
+import { transformerMetaWordHighlight } from '@shikijs/transformers';
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  base: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // TODO: replace this in makedocs!
+  title: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+  description: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+  lastUpdated: true,
+  cleanUrls: true,
+  outDir: 'REPLACE_ME_DOCUMENTER_VITEPRESS', // This is required for MarkdownVitepress to work correctly...
+  head: [['link', { rel: 'icon', href: '/DocumenterVitepress.jl/dev/favicon.ico' }]],
+
+  markdown: {
+    math: true,
+    config(md) {
+      md.use(tabsMarkdownPlugin),
+      md.use(mathjax3),
+      md.use(footnote)
+    },
+    theme: {
+      light: "github-light",
+      dark: "github-dark"
+    },
+    codeTransformers: [ transformerMetaWordHighlight(), ],
+
+  },
+  themeConfig: {
+    outline: 'deep',
+    // https://vitepress.dev/reference/default-theme-config
+    logo: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    search: {
+      provider: 'local',
+      options: {
+        detailedView: true
+      }
+    },
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Getting Started', link: '/design' },
+      { text: 'API', link: '/API' }
+    ],
+
+    sidebar: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    editLink: 'REPLACE_ME_DOCUMENTER_VITEPRESS',
+    socialLinks: [
+      { icon: 'github', link: 'REPLACE_ME_DOCUMENTER_VITEPRESS' }
+    ],
+    footer: {
+      message: 'Made with <a href="https://documenter.juliadocs.org/stable/" target="_blank"><strong>Documenter.jl</strong></a>, <a href="https://vitepress.dev" target="_blank"><strong>VitePress</strong></a> and <a href="https://luxdl.github.io/DocumenterVitepress.jl/stable/" target="_blank"><strong>DocumenterVitepress.jl</strong></a> <br>',
+      copyright: `© Copyright ${new Date().getUTCFullYear()}.`
+    }
+  }
+})

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

@@ -0,0 +1,21 @@
+// .vitepress/theme/index.ts
+import { h } from 'vue'
+import type { Theme } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+// import AsideTrustees from '../../components/AsideTrustees.vue'
+
+import { enhanceAppWithTabs } from 'vitepress-plugin-tabs/client'
+import './style.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout() {
+    return h(DefaultTheme.Layout, null, {
+      // 'home-hero-info-after': () => h(HomeTrustees),
+      // 'aside-ads-before': () => h(AsideTrustees),
+    })
+  },
+  enhanceApp({ app, router, siteData }) {
+    enhanceAppWithTabs(app)
+  }
+} satisfies Theme

docs/src/.vitepress/theme/style.css

@@ -0,0 +1,199 @@
+/* Customize default theme styling by overriding CSS variables:
+https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css
+ */
+
+  /* Layouts */
+
+/* 
+ :root {
+  --vp-layout-max-width: 1440px;
+} */
+
+.VPHero .clip {
+  white-space: pre;
+  max-width: 500px;
+}
+
+/* Fonts */
+
+@font-face {
+    font-family: JuliaMono-Regular;
+    src: url("https://cdn.jsdelivr.net/gh/cormullion/juliamono/webfonts/JuliaMono-Regular.woff2");
+}
+
+ :root {
+  /* Typography */
+  --vp-font-family-base: "Barlow", "Inter var experimental", "Inter var",
+    -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Oxygen, Ubuntu,
+    Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+
+  /* Code Snippet font */
+  --vp-font-family-mono: JuliaMono-Regular, monospace;
+
+}
+
+.mono {
+  /* 
+  Disable contextual alternates (kind of like ligatures but different) in monospace, 
+  which turns `/>` to an up arrow and `|>` (the Julia pipe symbol) to an up arrow as well.  
+  This is pretty bad for Julia folks reading even though copy+paste retains the same text.
+  */
+  font-feature-settings: 'calt' 0;
+  pre {
+    font-family: JuliaMono-Light;
+};
+code {
+    font-family: JuliaMono-Light;
+    };
+}
+
+/* Colors */
+
+:root {
+  --julia-blue: #4063D8;
+  --julia-purple: #9558B2;
+  --julia-red: #CB3C33;
+  --julia-green: #389826;
+
+  --vp-c-brand: #389826;
+  --vp-c-brand-light: #3dd027;
+  --vp-c-brand-lighter: #9499ff;
+  --vp-c-brand-lightest: #bcc0ff;
+  --vp-c-brand-dark: #535bf2;
+  --vp-c-brand-darker: #454ce1;
+  --vp-c-brand-dimm: #212425;
+}
+
+ /* Component: Button */
+
+:root {
+  --vp-button-brand-border: var(--vp-c-brand-light);
+  --vp-button-brand-text: var(--vp-c-white);
+  --vp-button-brand-bg: var(--vp-c-brand);
+  --vp-button-brand-hover-border: var(--vp-c-brand-light);
+  --vp-button-brand-hover-text: var(--vp-c-white);
+  --vp-button-brand-hover-bg: var(--vp-c-brand-light);
+  --vp-button-brand-active-border: var(--vp-c-brand-light);
+  --vp-button-brand-active-text: var(--vp-c-white);
+  --vp-button-brand-active-bg: var(--vp-button-brand-bg);
+}
+
+/* Component: Home */
+
+:root {
+  --vp-home-hero-name-color: transparent;
+  --vp-home-hero-name-background: -webkit-linear-gradient(
+    120deg,
+    #9558B2 30%,
+    #CB3C33
+  );
+
+  --vp-home-hero-image-background-image: linear-gradient(
+    -45deg,
+    #9558B2 30%,
+    #389826 30%,
+    #CB3C33 
+  );
+  --vp-home-hero-image-filter: blur(40px);
+}
+
+@media (min-width: 640px) {
+  :root {
+    --vp-home-hero-image-filter: blur(56px);
+  }
+}
+
+@media (min-width: 960px) {
+  :root {
+    --vp-home-hero-image-filter: blur(72px);
+  }
+}
+
+/* Component: Custom Block */
+
+:root.dark {
+  --vp-custom-block-tip-border: var(--vp-c-brand);
+  --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
+  --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
+
+    /* // Tweak the color palette for blacks and dark grays */
+    --vp-c-black: hsl(220 20% 9%);
+    --vp-c-black-pure: hsl(220, 24%, 4%);
+    --vp-c-black-soft: hsl(220 16% 13%);
+    --vp-c-black-mute: hsl(220 14% 17%);
+    --vp-c-gray: hsl(220 8% 56%);
+    --vp-c-gray-dark-1: hsl(220 10% 39%);
+    --vp-c-gray-dark-2: hsl(220 12% 28%);
+    --vp-c-gray-dark-3: hsl(220 12% 23%);
+    --vp-c-gray-dark-4: hsl(220 14% 17%);
+    --vp-c-gray-dark-5: hsl(220 16% 13%);
+
+    /* // Backgrounds */
+    /* --vp-c-bg: hsl(240, 2%, 11%); */
+    --vp-custom-block-info-bg: hsl(220 14% 17%);
+    /* --vp-c-gutter: hsl(220 20% 9%);
+
+    --vp-c-bg-alt: hsl(220 20% 9%);
+    --vp-c-bg-soft: hsl(220 14% 17%);
+    --vp-c-bg-mute: hsl(220 12% 23%);
+     */
+}
+
+ /* Component: Algolia */
+
+.DocSearch {
+  --docsearch-primary-color: var(--vp-c-brand) !important;
+}
+
+/* Component: MathJax */
+
+mjx-container > svg {
+  display: block;
+  margin: auto;
+}
+
+mjx-container {
+  padding: 0.5rem 0;
+}
+
+mjx-container {
+  display: inline-block;
+  margin: auto 2px -2px;
+}
+
+mjx-container > svg {
+  margin: auto;
+  display: inline-block;
+}
+
+/**
+ * Colors links
+ * -------------------------------------------------------------------------- */
+
+ :root {
+  --vp-c-brand-1: #CB3C33;
+  --vp-c-brand-2: #CB3C33;
+  --vp-c-brand-3: #CB3C33;
+  --vp-c-sponsor: #ca2971;
+  --vitest-c-sponsor-hover: #c13071;
+}
+
+.dark {
+  --vp-c-brand-1: #91dd33;
+  --vp-c-brand-2: #91dd33;
+  --vp-c-brand-3: #91dd33;
+  --vp-c-sponsor: #91dd33;
+  --vitest-c-sponsor-hover: #e51370;
+}
+
+/**
+ * Change images from light to dark theme
+ * -------------------------------------------------------------------------- */
+
+ :root:not(.dark) .dark-only {
+  display: none;
+}
+
+:root:is(.dark) .light-only {
+  display: none;
+}

docs/src/index.md

@@ -38,11 +38,6 @@ run!(model2, meteo_day)
 [![DOI](https://zenodo.org/badge/571659510.svg)](https://zenodo.org/badge/latestdoi/571659510)
 [![JOSS](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09/status.svg)](https://joss.theoj.org/papers/137e3e6c2ddc349bec39e06bb04e4e09)
 
-```@contents
-Pages = ["index.md"]
-Depth = 5
-```
-
 ## Overview
 
 `PlantSimEngine` is a comprehensive package for simulating and modelling plants, soil and atmosphere. It provides tools to **prototype, evaluate, test, and deploy** plant/crop models at any scale. At its core, PlantSimEngine is designed with a strong emphasis on performance and efficiency.