docs: build relative path to preview examples

.github/workflows/build-and-test.yaml

@@ -254,11 +254,11 @@ jobs:
           UV_INDEX_CODE_DOCS_THEME_PASSWORD: ${{ secrets.SIEMENS_NPM_TOKEN }}
       - run: npm run docs:build:generate
         env:
-          EXAMPLES_BASE: /element-examples
+          EXAMPLES_BASE: /element-examples/
         if: ${{ github.ref == 'refs/heads/main' }}
       - run: npm run docs:build:api
         env:
-          EXAMPLES_BASE: /element-examples
+          EXAMPLES_BASE: /element-examples/
         if: ${{ github.ref != 'refs/heads/main' }}
       - run: mv dist/element-examples/ dist/design/
       - run: mv dist/dashboards-demo/ dist/design/

mkdocs.yml

@@ -242,6 +242,7 @@ markdown_extensions:
   - md_in_html
   - element-docs:
       examples_base: !ENV [ EXAMPLES_BASE, 'http://localhost:4200' ]
+      md_file: !relative
   - toc:
       permalink: true
 

projects/element-docs-builder/md_extension_element_docs/extension.py

@@ -1,8 +1,9 @@
 import re
 import xml.etree.ElementTree as etree
 from abc import abstractmethod
-from typing import cast
-from urllib.parse import urlencode
+from pathlib import PurePosixPath
+from typing import Any, cast
+from urllib.parse import urlencode, urlparse
 
 from markdown import Extension
 from markdown.preprocessors import Preprocessor
@@ -96,9 +97,26 @@ def convert_tag(self, line) -> str:
     pass
 
 class ElementExamplePreProcessor(ElementHtmlPreProcessor):
-  def __init__(self, examples_base, *args, **kwargs):
-    """Initialize."""
+  def __init__(self, examples_base: str, page: str, *args: Any, **kwargs: Any) -> None:
+    """Initialize.
+
+    Args:
+      examples_base: Base URL for examples. Should include trailing slash
+                    for correct URL construction (e.g., '/element-examples/').
+      page: Current page's absolute URL from MkDocs context.
+    """
     self.examples_base = examples_base
+    self.page = page
+    url = urlparse(self.examples_base)
+    # If no scheme, we assume we need to build a relative path to the examples
+    if url.scheme == '':
+      segments = self.page.lstrip('/').split('/')
+      # Build a relative path to the root and join with the examples_base
+      base = PurePosixPath('/'.join(['..' if segment else '' for segment in segments]))
+      self.examples_base = str(base / self.examples_base.lstrip('/'))
+      if examples_base.endswith('/'):
+        self.examples_base += '/'
+
     super().__init__('si-docs-component', *args, **kwargs)
 
   def convert_tag(self, line) -> str:
@@ -132,13 +150,20 @@ class ElementDocsExtension(Extension):
   def __init__(self, *args, **kwargs):
     """Initialize."""
     self.config = {
-      'examples_base': ['', 'Base URL for the examples.']
+      'examples_base': ['', 'Base URL for the examples.'],
+      'md_file': ['', 'Helper for accessing the MkDocs config (set via !relative).']
     }
     super().__init__(*args, **kwargs)
 
   def extendMarkdown(self, md):
     """Add Tabbed to Markdown instance."""
-    md.preprocessors.register(ElementExamplePreProcessor(self.config.get('examples_base')[0], md), 'element_example', 10)
+    # Extract current page path
+    md_file_list = self.config.get('md_file', [''])
+    md_file_cfg = md_file_list[0] if md_file_list else ''
+    mkdocs_config = getattr(md_file_cfg, 'config', None)
+    current_page = getattr(mkdocs_config, '_current_page', None)
+    page = getattr(current_page, 'abs_url', '') or ''
+    md.preprocessors.register(ElementExamplePreProcessor(self.config.get('examples_base')[0], page, md), 'element_example', 10)
     md.treeprocessors.register(ElementTabTreeProcessor(md), 'element_tabs', 10)