mkdocs-likec4 1.0.0__py3-none-any.whl

mkdocs_likec4/generator.py

@@ -0,0 +1,73 @@
+import logging
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+from .parser import LikeC4Parser
+
+log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+
+
+class WebComponentGenerator:
+    """Generates LikeC4 web component JavaScript files."""
+
+    ASSETS_DIR = "assets/mkdocs_likec4"
+
+    @classmethod
+    def get_script_path(cls, project: Optional[str]) -> str:
+        """Get the site-relative path for a project's web component JS file."""
+        if project is None:
+            return f"{cls.ASSETS_DIR}/likec4_views.js"
+        return f"{cls.ASSETS_DIR}/likec4_views_{project}.js".lower()
+
+    @classmethod
+    def generate(
+        cls,
+        project_name: Optional[str],
+        project_dir: Optional[str],
+        build_dir: str,
+        site_dir: Path,
+    ) -> None:
+        """Generate web component JS file for a LikeC4 project."""
+        if project_name is not None and not LikeC4Parser.is_valid_identifier(
+            project_name
+        ):
+            log.error(
+                "mkdocs-likec4: Invalid project name '%s': must start with a letter "
+                "and contain only letters, numbers, hyphens, and underscores",
+                project_name,
+            )
+            return
+
+        site_dir.joinpath(cls.ASSETS_DIR).mkdir(parents=True, exist_ok=True)
+        dest_file = site_dir.joinpath(cls.get_script_path(project_name))
+
+        project_path = (
+            build_dir
+            if project_name is None
+            else str(Path(build_dir) / (project_dir or project_name))
+        )
+        log.info(
+            "mkdocs-likec4: Generating web component for %s from %s",
+            f"project '{project_name}'" if project_name else "default project",
+            project_path,
+        )
+
+        cmd = ["npx", "likec4", "codegen", "webcomponent"]
+        if project_name is not None:
+            cmd.extend(["--webcomponent-prefix", project_name.lower()])
+        cmd.extend([project_path, "-o", str(dest_file)])
+
+        try:
+            subprocess.run(cmd, check=True)
+        except subprocess.CalledProcessError as e:
+            log.error(
+                "mkdocs-likec4: Failed to generate web component for project '%s': %s",
+                project_name or "default",
+                e,
+            )
+        except FileNotFoundError:
+            log.error(
+                "mkdocs-likec4: 'npx' or 'likec4' command not found. "
+                "Ensure Node.js and likec4 are installed."
+            )

mkdocs_likec4/parser.py

@@ -0,0 +1,80 @@
+import logging
+import re
+from dataclasses import dataclass
+from html import escape
+from typing import Optional
+
+log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+
+IDENTIFIER_PATTERN = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]*$")
+
+
+@dataclass
+class ViewOptions:
+    """Options parsed from a likec4-view code block."""
+
+    view_id: str
+    browser: str = "true"
+    dynamic_variant: str = "diagram"
+    project: Optional[str] = None
+
+
+class LikeC4Parser:
+    """Parser for likec4-view markdown code blocks."""
+
+    PATTERN = re.compile(
+        r"```likec4-view([^\r\n]*)\r?\n(.+?)\r?\n```",
+        flags=re.DOTALL,
+    )
+    OPT_BROWSER = re.compile(r"\bbrowser=(true|false)\b")
+    OPT_VARIANT = re.compile(r"\bdynamic-variant=(diagram|sequence)\b")
+    OPT_PROJECT = re.compile(r"\bproject=([^\s]+)\b")
+
+    @classmethod
+    def is_valid_identifier(cls, value: str) -> bool:
+        """Validate that an identifier contains only safe characters."""
+        return bool(IDENTIFIER_PATTERN.match(value))
+
+    @classmethod
+    def parse_options(cls, options_text: str, view_id: str) -> ViewOptions:
+        """
+        Parse options from the opening fence line of a likec4-view block.
+
+        Options can appear in any order and are all optional with sensible defaults.
+        """
+        opts = ViewOptions(view_id=view_id)
+
+        if m := cls.OPT_BROWSER.search(options_text):
+            opts.browser = m.group(1)
+
+        if m := cls.OPT_VARIANT.search(options_text):
+            opts.dynamic_variant = m.group(1)
+
+        if m := cls.OPT_PROJECT.search(options_text):
+            opts.project = m.group(1)
+
+        return opts
+
+    @classmethod
+    def to_html(cls, opts: ViewOptions) -> str:
+        if not cls.is_valid_identifier(opts.view_id):
+            log.warning(
+                "mkdocs-likec4: Invalid view ID '%s': contains unsafe characters",
+                opts.view_id,
+            )
+
+        if opts.project and not cls.is_valid_identifier(opts.project):
+            log.warning(
+                "mkdocs-likec4: Invalid project name '%s': using 'likec4-view' tag",
+                opts.project,
+            )
+
+        tag = (
+            f"{opts.project.lower()}-view"
+            if opts.project and cls.is_valid_identifier(opts.project)
+            else "likec4-view"
+        )
+        return (
+            f'<{tag} view-id="{escape(opts.view_id, quote=True)}" '
+            f'browser="{opts.browser}" dynamic-variant="{opts.dynamic_variant}"></{tag}>'
+        )

mkdocs_likec4/plugin.py

@@ -0,0 +1,122 @@
+import logging
+from pathlib import Path
+from typing import Optional
+
+import pyjson5
+from mkdocs.plugins import BasePlugin
+from mkdocs.utils import get_relative_url
+
+from .generator import WebComponentGenerator
+from .parser import LikeC4Parser
+
+log = logging.getLogger(f"mkdocs.plugins.{__name__}")
+
+
+class LikeC4Plugin(BasePlugin):
+    """MkDocs plugin for embedding LikeC4 architecture diagrams."""
+
+    def __init__(self):
+        self.docs_dir = None
+        self.page_projects = {}
+        self.project_map = {}
+
+    def _discover_projects(self, docs_dir: Path):
+        """Discover LikeC4 projects by scanning for likec4.config.json files."""
+        if not docs_dir.exists():
+            log.warning("mkdocs-likec4: docs_dir does not exist: %s", docs_dir)
+            return
+
+        for config_file in docs_dir.rglob("likec4.config.json"):
+            try:
+                with config_file.open("r") as f:
+                    config_data = pyjson5.load(f)
+                if project_name := config_data.get("name"):
+                    project_dir = str(config_file.parent.relative_to(docs_dir))
+                    self.project_map[project_name] = project_dir
+                    log.info(
+                        "mkdocs-likec4: Discovered project '%s' at %s",
+                        project_name,
+                        project_dir,
+                    )
+            except (pyjson5.Json5Exception, OSError) as e:
+                log.warning("mkdocs-likec4: Failed to read %s: %s", config_file, e)
+
+        if not self.project_map:
+            self.project_map[None] = "."
+            log.info(
+                "mkdocs-likec4: No projects discovered, using default root project"
+            )
+
+    def _find_nearest_project(self, page_path: Path, docs_dir: Path) -> Optional[str]:
+        """Find the nearest LikeC4 project by traversing upward from the page."""
+        current = page_path.parent
+        while current >= docs_dir:
+            relative_str = str(current.relative_to(docs_dir))
+            for project_name, project_dir in self.project_map.items():
+                if project_dir == relative_str:
+                    return project_name
+            if current == docs_dir:
+                break
+            current = current.parent
+        return None
+
+    def on_config(self, config):
+        self.docs_dir = Path(config["docs_dir"])
+        self._discover_projects(self.docs_dir)
+        return config
+
+    def on_page_markdown(self, markdown: str, page, **kwargs) -> str:
+        """Parse likec4-view code blocks and replace with web component HTML."""
+        page_file = page.file.src_uri
+        projects_on_page = set()
+        page_path = self.docs_dir / page.file.src_path
+
+        def replacer(match):
+            options_text = (match.group(1) or "").strip()
+            view_id = match.group(2).strip()
+            opts = LikeC4Parser.parse_options(options_text, view_id)
+
+            if opts.project is None:
+                opts.project = self._find_nearest_project(page_path, self.docs_dir)
+                if opts.project:
+                    log.debug(
+                        "mkdocs-likec4: Auto-detected project '%s' for %s",
+                        opts.project,
+                        page_file,
+                    )
+
+            projects_on_page.add(opts.project)
+            return LikeC4Parser.to_html(opts)
+
+        markdown = LikeC4Parser.PATTERN.sub(replacer, markdown)
+        if projects_on_page:
+            self.page_projects[page_file] = projects_on_page
+        return markdown
+
+    def on_page_content(self, html, page, **kwargs):
+        """Inject project-specific JavaScript only on pages that use likec4-view."""
+        page_file = page.file.src_uri
+        if page_file not in self.page_projects:
+            return html
+
+        scripts = [
+            f'<script src="{get_relative_url(WebComponentGenerator.get_script_path(p), page.url)}"></script>'
+            for p in self.page_projects[page_file]
+        ]
+        return "\n".join(scripts) + "\n" + html
+
+    def on_post_build(self, config):
+        """Generate web component JS files for all projects used across the site."""
+        site_dir = Path(config["site_dir"])
+        all_projects = {p for projects in self.page_projects.values() for p in projects}
+
+        for project in all_projects:
+            if project in self.project_map:
+                WebComponentGenerator.generate(
+                    project, self.project_map[project], str(self.docs_dir), site_dir
+                )
+            else:
+                log.warning(
+                    "mkdocs-likec4: Skipping generation for undiscovered project: %s",
+                    project,
+                )

mkdocs_likec4-1.0.0.dist-info/METADATA

@@ -0,0 +1,48 @@
+Metadata-Version: 2.4
+Name: mkdocs-likec4
+Version: 1.0.0
+Summary: LikeC4 for MkDocs
+Author-email: Jonas Häusler <jonas.haeusler@doubleslash.de>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mkdocs>=1.6
+Requires-Dist: pyjson5>=2.0
+
+# mkdocs-likec4
+
+MkDocs plugin for embedding [LikeC4](https://likec4.dev/) architecture diagrams.
+
+## Quick Start
+
+1. Ensure `likec4` and `graphviz` are available on the build system.
+2. Install the `mkdocs-likec4` plugin via `pip`:
+  ```shell
+  pip install mkdocs-likec4
+  ```
+3.Add the plugin to your `mkdocs.yml`:
+  ```yaml
+  plugins:
+    - mkdocs-likec4
+  ```
+4. Start embedding views in your markdown:
+
+  ````markdown
+  ```likec4-view
+  <your-view-id>
+  ```
+  ````
+
+## Documentation
+
+For complete documentation with available options and examples, please read the **[Documentation](https://doubleslashde.github.io/mkdocs-likec4/)**.
+
+## Development
+
+### Registry setup
+
+Run `./local-preview` in your terminal to build and run a MkDocs server with the plugin installed,
+serving on <http://127.0.0.1:8000/>.
+
+## Releasing
+
+Trigger the manual `release` workflow via GitHub Actions.

mkdocs_likec4-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+mkdocs_likec4/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mkdocs_likec4/generator.py,sha256=eQRJA6Y0v-OEN27qrhvuUnECVSclsJuNcOXFTyT7HWg,2476
+mkdocs_likec4/parser.py,sha256=oXSWBZYjlPS_COGbY4Gk00M_C_dmsMiCxGpTWnUsAso,2487
+mkdocs_likec4/plugin.py,sha256=j3QR0UNlhmQlp2bgxJKgJzHc9ixQH5XvWDSuan_TOGc,4702
+mkdocs_likec4-1.0.0.dist-info/METADATA,sha256=9bpXNv5FCrcJUPQj58KrCExgsRLvHsu9OWT3A1p_FFU,1149
+mkdocs_likec4-1.0.0.dist-info/WHEEL,sha256=qELbo2s1Yzl39ZmrAibXA2jjPLUYfnVhUNTlyF1rq0Y,92
+mkdocs_likec4-1.0.0.dist-info/entry_points.txt,sha256=yTY55XeHbJmJzDPLuQ7QsC5VA0_yu0G45swAWa3tNA8,60
+mkdocs_likec4-1.0.0.dist-info/top_level.txt,sha256=-ogze9a_5heAOroarc-uU6RpCdJzYuZnToH0gVek58k,14
+mkdocs_likec4-1.0.0.dist-info/RECORD,,

mkdocs_likec4-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_likec4-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+likec4 = mkdocs_likec4.plugin:LikeC4Plugin

mkdocs_likec4-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_likec4