Add mermaid rendering in docs

docs/.vitepress/config.ts

@@ -1,57 +1,74 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from "vitepress";
+import { withMermaid } from "vitepress-plugin-mermaid";
 
-export default defineConfig({
-  title: 'etter',
-  description: 'Natural language geographic query parsing using LLMs',
+const baseConfig = defineConfig({
+  title: "etter",
+  description: "Natural language geographic query parsing using LLMs",
 
-  base: '/etter/',
+  base: "/etter/",
 
   // /api/ is generated by pdoc at build time and does not exist as .md files
   ignoreDeadLinks: [/\/api\//],
   head: [
-    ['link', { rel: 'preconnect', href: 'https://fonts.googleapis.com' }],
-    ['link', { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' }],
-    ['link', { href: 'https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&display=swap', rel: 'stylesheet' }],
+    ["link", { rel: "preconnect", href: "https://fonts.googleapis.com" }],
+    ["link", { rel: "preconnect", href: "https://fonts.gstatic.com", crossorigin: "" }],
+    [
+      "link",
+      {
+        href: "https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600&display=swap",
+        rel: "stylesheet",
+      },
+    ],
   ],
 
   themeConfig: {
-    logo: '/etter-logo.png',
-    siteTitle: 'etter',
+    logo: "/etter-logo.png",
+    siteTitle: "etter",
 
     nav: [
-      { text: 'Guide', link: '/guide/getting-started' },
-      { text: 'API Reference', link: '/api/etter.html' },
+      { text: "Guide", link: "/guide/getting-started" },
+      { text: "API Reference", link: "/api/etter.html" },
     ],
 
     sidebar: [
       {
-        text: 'Guide',
+        text: "Guide",
         items: [
-          { text: 'Getting Started', link: '/guide/getting-started' },
-          { text: 'Spatial Relations', link: '/guide/spatial-relations' },
-          { text: 'Datasources', link: '/guide/datasources' },
-          { text: 'Error Handling', link: '/guide/error-handling' },
+          { text: "Getting Started", link: "/guide/getting-started" },
+          { text: "Spatial Relations", link: "/guide/spatial-relations" },
+          { text: "Datasources", link: "/guide/datasources" },
+          { text: "Error Handling", link: "/guide/error-handling" },
         ],
       },
       {
-        text: 'Reference',
-        items: [
-          { text: 'API Reference', link: '/api/etter.html' },
-        ],
+        text: "Reference",
+        items: [{ text: "API Reference", link: "/api/etter.html" }],
       },
     ],
 
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/geoblocks/etter' },
-    ],
+    socialLinks: [{ icon: "github", link: "https://github.com/geoblocks/etter" }],
 
     footer: {
-      message: 'Released under the BSD-3-Clause License.',
+      message: "Released under the BSD-3-Clause License.",
       copyright: 'Sponsored by <a href="https://www.camptocamp.com" target="_blank">Camptocamp</a>',
     },
 
     search: {
-      provider: 'local',
+      provider: "local",
     },
   },
-})
+});
+
+const extendedConfig = withMermaid({
+  ...baseConfig,
+  // optionally, you can pass MermaidConfig
+  mermaid: {
+    // refer https://mermaid.js.org/config/setup/modules/mermaidAPI.html#mermaidapi-configuration-defaults for options
+  },
+  // optionally set additional config for plugin itself with MermaidPluginConfig
+  mermaidPlugin: {
+    class: "mermaid my-class", // set additional css classes for parent container
+  },
+});
+
+export default extendedConfig;

docs/guide/getting-started.md

@@ -8,18 +8,35 @@ etter transforms natural language location queries into structured geographic fi
 
 **Key principle:** etter has one responsibility — extract the geographic filter. It does not identify features, filter attributes, or execute searches.
 
-```
-User query: "Hiking with children north of Lausanne"
-                      ↓
-Parent app  →  extracts: Activity="Hiking", Audience="children"
-                      ↓
-etter       →  parses:   relation="north_of", location="Lausanne"
-                      ↓
-Parent app  →  queries:  WHERE activity='hiking' AND ST_Intersects(location, sector)
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User
+    participant App as Parent app
+    participant Etter as etter
+    participant DB as Database
+
+    User->>App: "Hiking with children north of Lausanne"
+
+    %% Parent app internal processing
+    App->>App: extracts: Activity="Hiking", Audience="children"
+
+    %% Forwarding spatial data to etter
+    App->>Etter: Request spatial parsing
+    Etter->>Etter: parses: relation="north_of", location="Lausanne"
+    Etter-->>App: Returns spatial parameters
+
+    %% Final database query
+    App->>DB: queries: WHERE activity='hiking' AND ST_Intersects(location, sector)
 ```
 
 ## Installation
 
+<!-- TODO: Once published to PyPI, update these instructions to use `pip install etter` -->
+
+> [!NOTE]
+> So far etter is not published to PyPI, we will update these instructions once it's available through pip.
+
 ```bash
 git clone https://github.com/geoblocks/etter.git
 cd etter