Reintroduce interactive diagrams (#2388)

SVGs are normally included as images which makes them non-interactive.
They can be imported and included as html, but this requires one to
include them in a setup script. This PR adds a small plugin to parse md
image links and include them as html:

```
![](assets/cxl/expr.drawio.svg)       <-- using an img tag
![](assets/cxl/expr.drawio.svg?raw)   <-- using an svg tag (included as v-html by plugin)
```

In VSCode and Github, the rendered markdown ignores the `?raw`, so the
image is still displayed when rendered and can be navigated to.

The cxl diagrams now also again contain links to the sections (every
element with a name now contains a link, even if it is to the same
section).

---------

Co-authored-by: Daniel Hutzel <daniel.hutzel@sap.com>

Author: Akatuoro

.vitepress/config.js

@@ -194,10 +194,12 @@ if (process.env.VITE_CAPIRE_EXTRA_ASSETS) {
 import { dl } from '@mdit/plugin-dl'
 import * as MdAttrsPropagate from './lib/md-attrs-propagate'
 import * as MdTypedModels from './lib/md-typed-models'
+import * as MdDiagramSvg from './lib/md-diagram-svg'
 
 config.markdown.config = md => {
   MdAttrsPropagate.install(md)
   MdTypedModels.install(md)
+  MdDiagramSvg.install(md)
   md.use(dl)
 }
 

.vitepress/lib/md-diagram-svg.ts

@@ -0,0 +1,51 @@
+import { MarkdownEnv, MarkdownRenderer } from 'vitepress'
+
+/**
+ * Renders SVG diagrams in markdown files as <svg> element.
+ * This allows the diagrams to be interactive.
+ *
+ * To use, add `?raw` to the end of the image source, e.g. `![](diagram.svg?raw)`.
+ */
+export function install(md: MarkdownRenderer) {
+  const defaultImage =
+    md.renderer.rules.image ||
+    ((tokens, idx, options, env, self) => self.renderToken(tokens, idx, options))
+
+  md.renderer.rules.image = (tokens, idx, options, env: MarkdownEnv, self) => {
+    const token = tokens[idx]
+    const src = token.attrGet('src') || ''
+
+    if (!/\.svg\?raw$/.test(src)) {
+        return defaultImage(tokens, idx, options, env, self)
+    }
+
+    const name = 'svg_' + src.replace('?raw', '').replace(/[^a-zA-Z0-9_]/g, '_') // stable variable name for the imported SVG content
+    const importPath = src.startsWith('/') && src.startsWith('.') ? src : './' + src
+
+    const sfcBlocks = env.sfcBlocks! 
+    if (!sfcBlocks.scriptSetup) {
+      sfcBlocks.scriptSetup = {
+        content: '<script setup>\n</script>',
+        contentStripped: '\n',
+        tagClose: '</script>',
+        tagOpen: '<script setup>',
+        type: 'script'
+      }
+      sfcBlocks.scripts.push(sfcBlocks.scriptSetup)
+    }
+
+    const { scriptSetup } = sfcBlocks
+    const { tagOpen, tagClose, contentStripped: rest } = scriptSetup
+
+    const imp = `import ${name} from "${importPath}";`
+
+    if (!scriptSetup.content.includes(imp)) {
+      scriptSetup.contentStripped = `${imp}\n${rest}`
+      scriptSetup.content = `${tagOpen}${imp}\n${rest}${tagClose}`
+    }
+
+    // use v-html to render the SVG content as actual elements
+    // with v-html, vite's HMR update works on diagram change
+    return `<span class="diagram" v-html="${name}"></span>`
+  }
+}

.vitepress/theme/styles.scss

@@ -312,6 +312,23 @@ img, video.bright {
   }
 }
 
+// Raw svg diagrams
+.diagram {
+  all: initial; // preserve original svg formatting
+  svg {
+    .dark & { // recolor in dark mode
+      filter: brightness(.884) invert(1) hue-rotate(177deg);
+    }
+    max-width: 100%;
+    height: auto;
+    margin: 30px auto;
+
+    * {
+      // drawio line-height is not updated when font size is changed leading to misaligned text
+      line-height: unset !important;
+    }
+  }
+}
 
 
 .VPBadge {

cds/assets/cxl/expr.drawio.svg

@@ -85,7 +85,7 @@ select from Books {
 
 This syntax diagram describes the possible expressions:
 
-![](assets/cxl/expr.drawio.svg)
+![](assets/cxl/expr.drawio.svg?raw)
 
 > Using:
 > [Path Expressions](#ref),
@@ -262,7 +262,7 @@ A `ref` (short for reference) is used to refer to an element within the model.
 It can be used to navigate along path segments. Such a navigation is often
 referred to as a **path expression**.
 
-![](assets/cxl/ref.drawio.svg)
+![](assets/cxl/ref.drawio.svg?raw)
 
 > Using:
 > [Infix Filters](#infix-filters)
@@ -459,7 +459,7 @@ If we apply this terminology to [path-expressions](#ref), an infix filter condit
 that is applied to a path-segment of a [path-expression](#ref).
 This allows you to filter the target of an association based on certain criteria.
 
-![](assets/cxl/infix-filter.drawio.svg)
+![](assets/cxl/infix-filter.drawio.svg?raw)
 
 > Using:
 > [Expressions](#expr)
@@ -778,7 +778,7 @@ navigates along the `author` association of the `Books` entity only if the autho
 
 As depicted in below excerpt of the syntax diagram for `expr`, CXL supports all the standard SQL operators as well as a few additional ones, such as the `?` operator to check for the existence of a path.
 
-![](assets/cxl/operators.drawio.svg)
+![](assets/cxl/operators.drawio.svg?raw)
 
 > Using:
 > [Expressions](#expr)
@@ -814,7 +814,7 @@ Following table gives an overview of the guaranteed supported operators in CXL:
 ## Functions (`func`)
 ###### func
 
-![](assets/cxl/function.drawio.svg)
+![](assets/cxl/function.drawio.svg?raw)
 
 > Using:
 > [Expressions](#expr)