PB-2066 Replace SVG diagram with mermaid diagram #patch

.vitepress/config.mts

@@ -1,19 +1,18 @@
 import { defineConfig, type DefaultTheme } from 'vitepress'
 import fs from 'fs'
 
-// https://vitepress.dev/reference/site-config
 export default defineConfig({
     title: '*.geo.admin.ch',
     description: 'Technical Documentation about *.geo.admin.ch',
     /*
-  Prepend a base path such that links still work when the page is built for the
-  preview in a PR ('test link' in the PR description).
+        Prepend a base path such that links still work when the page is built for the
+        preview in a PR ('test link' in the PR description).
 
-  For example, VITE_BASE_URL would be set to '/preview/feat-pb-1234-my-branch/'
-  for a link like this:
+        For example, VITE_BASE_URL would be set to '/preview/feat-pb-1234-my-branch/'
+        for a link like this:
 
-     https://sys-docs.dev.bgdi.ch/preview/feat-pb-1234-my-branch/index.html
-  */
+        https://sys-docs.dev.bgdi.ch/preview/feat-pb-1234-my-branch/index.html
+        */
     base: process.env.VITE_BASE_URL || '/',
     head: [
         ['link', { rel: 'icon', href: '/favicon.ico' }],

.vitepress/theme/custom.css

@@ -30,6 +30,30 @@ figcaption {
     border-color: transparent !important;
 }
 
+.mermaid-container {
+    height: 300px !important;
+    max-height: 300px !important;
+}
+
+.mermaid svg {
+    display: block;
+    width: 100%;
+    height: 300px;
+    margin: 0;
+    padding: 0;
+}
+
+@media (min-width: 768px) {
+    .mermaid-container {
+        height: 600px !important;
+        max-height: 600px !important;
+    }
+
+    .mermaid svg {
+        height: 600px;
+    }
+}
+
 /* ==========================
    2. Layout Styles
    ========================== */

.vitepress/theme/index.ts

@@ -1,10 +1,12 @@
+import { h, nextTick, watch } from 'vue'
 import type { Theme } from 'vitepress'
 import DefaultTheme from 'vitepress/theme'
 import ApiCodeBlock from '../../components/ApiCodeBlock.vue'
 import './custom.css'
 import ExampleCodeBlock from '../../components/ExampleCodeBlock.vue'
 import { createHighlighter } from 'shiki'
 import type { HighlighterGeneric, BundledLanguage, BundledTheme } from 'shiki'
+import { createMermaidRenderer } from 'vitepress-mermaid-renderer'
 
 // Create a global instance of the highlighter as Shiki is supposed to be used as a singleton
 const highlighterPromise = createHighlighter({
@@ -14,6 +16,27 @@ const highlighterPromise = createHighlighter({
 
 export default {
     extends: DefaultTheme,
+    Layout: () => {
+        const initMermaid = () => {
+            const mermaidRenderer = createMermaidRenderer({
+                theme: 'forest',
+                flowchart: { useMaxWidth: true },
+            })
+        }
+
+        // initial mermaid setup
+        nextTick(() => initMermaid())
+
+        // on theme change, re-render mermaid charts
+        watch(
+            () => document.documentElement.getAttribute('data-theme'),
+            () => {
+                initMermaid()
+            }
+        )
+
+        return h(DefaultTheme.Layout)
+    },
     async enhanceApp({ app }) {
         // register custom global components
         app.component('ApiCodeBlock', ApiCodeBlock)

download-data/stac-api/asset-upload.md

@@ -194,6 +194,50 @@ The following example illustrates best practices for handling errors during repe
    | `500 Internal Server Error`                                         | Cancel upload. Report to service administrator (retry usually useless).            |
    | `502 Bad Gateway`, `503 Service Unavailable`, `504 Gateway Timeout` | Service is momentarily not available, wait a short moment, then retry the request. |
 
-   The following figure shows the flow of a multipart upload process.
-
-   <img src="../../static/service-stac-upload-process.svg" />
+The following figure shows the flow of a multipart upload process.
+
+```mermaid
+flowchart TD
+    start(("Start"))
+
+    s1["Step 1: POST <br>/assets/{assetId}/uploads"]
+    s2["Step 2: PUT<br>{presigned url}"]
+    s3["Step 3: POST<br>/assets/{assetId}/uploads/{uploadId}/complete"]
+
+    in_progress{"description = 'upload in progress'"}
+    get["GET<br>/assets/{assetId}/uploads?status=in-progress"]
+    post["POST<br>/assets/{assetId}/uploads/{uploadId}/abort"]
+    debug["debug manually"]
+
+    retry_step2{"Retry?"}
+    retry_step3{"Retry?"}
+    retry_end{"Retry?"}
+
+    sleep_step2["SLEEP<br>(200ms)"]
+    sleep_step3["SLEEP<br>(200ms)"]
+
+    ending(("End"))
+
+    start --> s1
+    s1 -->|201| s2
+    s2 -->|200| s3
+    s3 -->|200| ending
+
+    s1 -->|400| in_progress
+    in_progress -->|no| debug
+    in_progress -->|yes| get
+    get --> post
+    post --> retry_end
+    retry_end -->|yes| s1
+    retry_end -->|no| ending
+
+    s2 -->|400<br>50X| retry_step2
+    retry_step2 -->|yes| sleep_step2
+    sleep_step2 --> s2
+    retry_step2 -->|no| post
+
+    s3 -->|50X| retry_step3
+    retry_step3 -->|yes| sleep_step3
+    sleep_step3 --> s1
+    retry_step3 -->|no| ending
+```