mkdocs-likec4 1.0.0__tar.gz

mkdocs_likec4-1.0.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,38 @@
+# 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/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-1.0.0/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-1.0.0/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/mkdocs_likec4.egg-info/PKG-INFO

@@ -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/mkdocs_likec4.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+README.md
+pyproject.toml
+mkdocs_likec4/__init__.py
+mkdocs_likec4/generator.py
+mkdocs_likec4/parser.py
+mkdocs_likec4/plugin.py
+mkdocs_likec4.egg-info/PKG-INFO
+mkdocs_likec4.egg-info/SOURCES.txt
+mkdocs_likec4.egg-info/dependency_links.txt
+mkdocs_likec4.egg-info/entry_points.txt
+mkdocs_likec4.egg-info/requires.txt
+mkdocs_likec4.egg-info/top_level.txt
+tests/test_generator.py
+tests/test_parser.py
+tests/test_plugin.py

mkdocs_likec4-1.0.0/mkdocs_likec4.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mkdocs_likec4-1.0.0/mkdocs_likec4.egg-info/entry_points.txt

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

mkdocs_likec4-1.0.0/mkdocs_likec4.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mkdocs>=1.6
+pyjson5>=2.0

mkdocs_likec4-1.0.0/mkdocs_likec4.egg-info/top_level.txt

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

mkdocs_likec4-1.0.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mkdocs-likec4"
+description = "LikeC4 for MkDocs"
+version = "1.0.0"
+authors = [{ name = "Jonas Häusler", email = "jonas.haeusler@doubleslash.de" }]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "mkdocs>=1.6",
+  "pyjson5>=2.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["mkdocs_likec4*"]
+
+[project.entry-points."mkdocs.plugins"]
+"likec4" = "mkdocs_likec4.plugin:LikeC4Plugin"
+
+[tool.commitizen]
+name = "cz_customize"
+tag_format = "v$version"
+version_provider = "uv"
+version_files = [
+    "pyproject.toml:version"
+]
+
+[tool.commitizen.customize]
+bump_pattern = '^(feat|fix|ci|build|perf|refactor|chore)'
+bump_map = { feat = "MINOR", fix = "PATCH", ci = "PATCH", build = "PATCH", perf = "PATCH", refactor = "PATCH", 'chore' = "PATCH" }
+schema_pattern = '^(build|ci|docs|feat|fix|perf|refactor|style|test|chore|revert|bump|chore)(\(\S+\))?\:?\s.*'
+
+[dependency-groups]
+dev = [
+    "commitizen>=3.31.0",
+    "ruff>=0.14.11",
+]
+test = [
+    "pytest>=8.0",
+]

mkdocs_likec4-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mkdocs_likec4-1.0.0/tests/test_generator.py

@@ -0,0 +1,157 @@
+"""Tests for the LikeC4 generator module."""
+
+import subprocess
+from unittest.mock import patch
+
+from mkdocs_likec4.generator import WebComponentGenerator
+
+
+class TestGetScriptPath:
+    """Tests for the get_script_path method."""
+
+    def test_default_project_path(self):
+        """Test script path for default (None) project."""
+        path = WebComponentGenerator.get_script_path(None)
+        assert path == "assets/mkdocs_likec4/likec4_views.js"
+
+    def test_named_project_path(self):
+        """Test script path for named project."""
+        path = WebComponentGenerator.get_script_path("myproject")
+        assert path == "assets/mkdocs_likec4/likec4_views_myproject.js"
+
+    def test_uppercase_project_lowercased(self):
+        """Test that uppercase project names are lowercased."""
+        path = WebComponentGenerator.get_script_path("MyProject")
+        assert path == "assets/mkdocs_likec4/likec4_views_myproject.js"
+
+    def test_mixed_case_project(self):
+        """Test mixed case project name."""
+        path = WebComponentGenerator.get_script_path("My-Project_123")
+        assert path == "assets/mkdocs_likec4/likec4_views_my-project_123.js"
+
+
+class TestGenerate:
+    """Tests for the generate method."""
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_default_project(self, mock_run, tmp_path):
+        """Test generating web component for default project."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+
+        WebComponentGenerator.generate(
+            project_name=None,
+            project_dir=None,
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+        mock_run.assert_called_once()
+        call_args = mock_run.call_args[0][0]
+        call_kwargs = mock_run.call_args[1]
+        assert call_args[0] == "npx"
+        assert call_args[1] == "likec4"
+        assert call_args[2] == "codegen"
+        assert call_args[3] == "webcomponent"
+        assert "/docs" in call_args[4]
+        assert "--webcomponent-prefix" not in call_args
+        # Verify check=True is passed for proper error handling
+        assert call_kwargs.get("check") is True
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_named_project(self, mock_run, tmp_path):
+        """Test generating web component for named project."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+
+        WebComponentGenerator.generate(
+            project_name="myproject",
+            project_dir="subdir",
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+        mock_run.assert_called_once()
+        call_args = mock_run.call_args[0][0]
+        assert "--webcomponent-prefix" in call_args
+        prefix_idx = call_args.index("--webcomponent-prefix")
+        assert call_args[prefix_idx + 1] == "myproject"
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_creates_assets_dir(self, mock_run, tmp_path):
+        """Test that generate creates the assets directory."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+
+        WebComponentGenerator.generate(
+            project_name=None,
+            project_dir=None,
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+        assets_dir = site_dir / "assets" / "mkdocs_likec4"
+        assert assets_dir.exists()
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_invalid_project_name_skipped(self, mock_run, tmp_path):
+        """Test that invalid project names are skipped."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+
+        WebComponentGenerator.generate(
+            project_name="123invalid",
+            project_dir=None,
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+        mock_run.assert_not_called()
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_handles_subprocess_error(self, mock_run, tmp_path):
+        """Test that subprocess errors are handled gracefully."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+        mock_run.side_effect = subprocess.CalledProcessError(1, "cmd")
+
+        # Should not raise
+        WebComponentGenerator.generate(
+            project_name=None,
+            project_dir=None,
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_handles_file_not_found(self, mock_run, tmp_path):
+        """Test that FileNotFoundError is handled gracefully."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+        mock_run.side_effect = FileNotFoundError("npx not found")
+
+        # Should not raise
+        WebComponentGenerator.generate(
+            project_name=None,
+            project_dir=None,
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+    @patch("mkdocs_likec4.generator.subprocess.run")
+    def test_generate_output_path(self, mock_run, tmp_path):
+        """Test that output path is correct."""
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+
+        WebComponentGenerator.generate(
+            project_name="proj",
+            project_dir="projdir",
+            build_dir="/docs",
+            site_dir=site_dir,
+        )
+
+        call_args = mock_run.call_args[0][0]
+        output_idx = call_args.index("-o")
+        output_path = call_args[output_idx + 1]
+        assert "likec4_views_proj.js" in output_path

mkdocs_likec4-1.0.0/tests/test_parser.py

@@ -0,0 +1,266 @@
+"""Tests for the LikeC4 parser module."""
+
+from mkdocs_likec4.parser import LikeC4Parser, ViewOptions
+
+
+class TestViewOptions:
+    """Tests for the ViewOptions dataclass."""
+
+    def test_default_values(self):
+        """Test that ViewOptions has correct default values."""
+        opts = ViewOptions(view_id="test-view")
+        assert opts.view_id == "test-view"
+        assert opts.browser == "true"
+        assert opts.dynamic_variant == "diagram"
+        assert opts.project is None
+
+    def test_custom_values(self):
+        """Test ViewOptions with custom values."""
+        opts = ViewOptions(
+            view_id="my-view",
+            browser="false",
+            dynamic_variant="sequence",
+            project="myproject",
+        )
+        assert opts.view_id == "my-view"
+        assert opts.browser == "false"
+        assert opts.dynamic_variant == "sequence"
+        assert opts.project == "myproject"
+
+
+class TestLikeC4ParserPattern:
+    """Tests for the regex pattern matching."""
+
+    def test_basic_code_block(self):
+        """Test matching a basic likec4-view code block."""
+        markdown = """```likec4-view
+my-view-id
+```"""
+        match = LikeC4Parser.PATTERN.search(markdown)
+        assert match is not None
+        assert match.group(1) == ""
+        assert match.group(2) == "my-view-id"
+
+    def test_code_block_with_options(self):
+        """Test matching a code block with options."""
+        markdown = """```likec4-view browser=false project=myproj
+view-id-here
+```"""
+        match = LikeC4Parser.PATTERN.search(markdown)
+        assert match is not None
+        assert "browser=false" in match.group(1)
+        assert "project=myproj" in match.group(1)
+        assert match.group(2) == "view-id-here"
+
+    def test_no_match_for_other_code_blocks(self):
+        """Test that other code blocks don't match."""
+        markdown = """```python
+print("hello")
+```"""
+        match = LikeC4Parser.PATTERN.search(markdown)
+        assert match is None
+
+    def test_multiple_code_blocks(self):
+        """Test finding multiple code blocks."""
+        markdown = """```likec4-view
+view1
+```
+
+Some text
+
+```likec4-view project=proj2
+view2
+```"""
+        matches = list(LikeC4Parser.PATTERN.finditer(markdown))
+        assert len(matches) == 2
+        assert matches[0].group(2) == "view1"
+        assert matches[1].group(2) == "view2"
+
+
+class TestParseOptions:
+    """Tests for the parse_options method."""
+
+    def test_empty_options(self):
+        """Test parsing empty options string."""
+        opts = LikeC4Parser.parse_options("", "test-view")
+        assert opts.view_id == "test-view"
+        assert opts.browser == "true"
+        assert opts.dynamic_variant == "diagram"
+        assert opts.project is None
+
+    def test_browser_option_true(self):
+        """Test parsing browser=true option."""
+        opts = LikeC4Parser.parse_options("browser=true", "view")
+        assert opts.browser == "true"
+
+    def test_browser_option_false(self):
+        """Test parsing browser=false option."""
+        opts = LikeC4Parser.parse_options("browser=false", "view")
+        assert opts.browser == "false"
+
+    def test_dynamic_variant_diagram(self):
+        """Test parsing dynamic-variant=diagram option."""
+        opts = LikeC4Parser.parse_options("dynamic-variant=diagram", "view")
+        assert opts.dynamic_variant == "diagram"
+
+    def test_dynamic_variant_sequence(self):
+        """Test parsing dynamic-variant=sequence option."""
+        opts = LikeC4Parser.parse_options("dynamic-variant=sequence", "view")
+        assert opts.dynamic_variant == "sequence"
+
+    def test_project_option(self):
+        """Test parsing project option."""
+        opts = LikeC4Parser.parse_options("project=myproject", "view")
+        assert opts.project == "myproject"
+
+    def test_multiple_options(self):
+        """Test parsing multiple options."""
+        opts = LikeC4Parser.parse_options(
+            "browser=false dynamic-variant=sequence project=proj1", "view"
+        )
+        assert opts.browser == "false"
+        assert opts.dynamic_variant == "sequence"
+        assert opts.project == "proj1"
+
+    def test_options_in_any_order(self):
+        """Test that options can appear in any order."""
+        opts = LikeC4Parser.parse_options(
+            "project=proj browser=false dynamic-variant=sequence", "view"
+        )
+        assert opts.browser == "false"
+        assert opts.dynamic_variant == "sequence"
+        assert opts.project == "proj"
+
+    def test_invalid_browser_value_ignored(self):
+        """Test that invalid browser value is ignored."""
+        opts = LikeC4Parser.parse_options("browser=invalid", "view")
+        assert opts.browser == "true"  # default
+
+    def test_invalid_variant_value_ignored(self):
+        """Test that invalid dynamic-variant value is ignored."""
+        opts = LikeC4Parser.parse_options("dynamic-variant=invalid", "view")
+        assert opts.dynamic_variant == "diagram"  # default
+
+
+class TestIsValidIdentifier:
+    """Tests for the is_valid_identifier method."""
+
+    def test_valid_simple_name(self):
+        """Test valid simple identifier."""
+        assert LikeC4Parser.is_valid_identifier("project") is True
+
+    def test_valid_name_with_numbers(self):
+        """Test valid identifier with numbers."""
+        assert LikeC4Parser.is_valid_identifier("project123") is True
+
+    def test_valid_name_with_hyphen(self):
+        """Test valid identifier with hyphen."""
+        assert LikeC4Parser.is_valid_identifier("my-project") is True
+
+    def test_valid_name_with_underscore(self):
+        """Test valid identifier with underscore."""
+        assert LikeC4Parser.is_valid_identifier("my_project") is True
+
+    def test_valid_mixed_name(self):
+        """Test valid identifier with mixed characters."""
+        assert LikeC4Parser.is_valid_identifier("My-Project_123") is True
+
+    def test_invalid_starts_with_number(self):
+        """Test invalid identifier starting with number."""
+        assert LikeC4Parser.is_valid_identifier("123project") is False
+
+    def test_invalid_starts_with_hyphen(self):
+        """Test invalid identifier starting with hyphen."""
+        assert LikeC4Parser.is_valid_identifier("-project") is False
+
+    def test_invalid_contains_space(self):
+        """Test invalid identifier with space."""
+        assert LikeC4Parser.is_valid_identifier("my project") is False
+
+    def test_invalid_contains_special_chars(self):
+        """Test invalid identifier with special characters."""
+        assert LikeC4Parser.is_valid_identifier("project@name") is False
+        assert LikeC4Parser.is_valid_identifier("project.name") is False
+        assert LikeC4Parser.is_valid_identifier("project/name") is False
+
+    def test_invalid_empty_string(self):
+        """Test invalid empty identifier."""
+        assert LikeC4Parser.is_valid_identifier("") is False
+
+    def test_invalid_with_quotes(self):
+        """Test invalid identifier with quotes (XSS attempt)."""
+        assert LikeC4Parser.is_valid_identifier('view" onclick="alert(1)') is False
+
+    def test_invalid_with_angle_brackets(self):
+        """Test invalid identifier with angle brackets."""
+        assert LikeC4Parser.is_valid_identifier("view<script>") is False
+
+
+class TestToHtml:
+    """Tests for the to_html method."""
+
+    def test_basic_html_output(self):
+        """Test basic HTML output without project."""
+        opts = ViewOptions(view_id="my-view")
+        html = LikeC4Parser.to_html(opts)
+        assert (
+            html
+            == '<likec4-view view-id="my-view" browser="true" dynamic-variant="diagram"></likec4-view>'
+        )
+
+    def test_html_with_project(self):
+        """Test HTML output with valid project."""
+        opts = ViewOptions(view_id="my-view", project="myproject")
+        html = LikeC4Parser.to_html(opts)
+        assert (
+            html
+            == '<myproject-view view-id="my-view" browser="true" dynamic-variant="diagram"></myproject-view>'
+        )
+
+    def test_html_with_uppercase_project(self):
+        """Test HTML output with uppercase project (should be lowercased)."""
+        opts = ViewOptions(view_id="my-view", project="MyProject")
+        html = LikeC4Parser.to_html(opts)
+        assert (
+            html
+            == '<myproject-view view-id="my-view" browser="true" dynamic-variant="diagram"></myproject-view>'
+        )
+
+    def test_html_with_custom_options(self):
+        """Test HTML output with custom options."""
+        opts = ViewOptions(
+            view_id="test",
+            browser="false",
+            dynamic_variant="sequence",
+            project="proj",
+        )
+        html = LikeC4Parser.to_html(opts)
+        assert (
+            html
+            == '<proj-view view-id="test" browser="false" dynamic-variant="sequence"></proj-view>'
+        )
+
+    def test_html_with_invalid_project_falls_back(self):
+        """Test HTML output with invalid project name falls back to likec4-view."""
+        opts = ViewOptions(view_id="my-view", project="123invalid")
+        html = LikeC4Parser.to_html(opts)
+        assert (
+            html
+            == '<likec4-view view-id="my-view" browser="true" dynamic-variant="diagram"></likec4-view>'
+        )
+
+    def test_html_escapes_invalid_view_id_with_quotes(self):
+        """Test that invalid view ID with quotes is escaped to prevent XSS."""
+        opts = ViewOptions(view_id='view" onclick="alert(1)')
+        html = LikeC4Parser.to_html(opts)
+        # Should escape quotes
+        assert "onclick" not in html or "&quot;" in html
+        assert '"alert' not in html
+
+    def test_html_escapes_invalid_view_id_with_angle_brackets(self):
+        """Test that invalid view ID with angle brackets is escaped."""
+        opts = ViewOptions(view_id="view<script>alert(1)</script>")
+        html = LikeC4Parser.to_html(opts)
+        # Should escape angle brackets
+        assert "<script>" not in html
+        assert "&lt;" in html or "script" not in html

mkdocs_likec4-1.0.0/tests/test_plugin.py

@@ -0,0 +1,358 @@
+"""Tests for the LikeC4 plugin module."""
+
+import json
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from mkdocs_likec4.plugin import LikeC4Plugin
+
+
+@pytest.fixture
+def plugin():
+    """Create a fresh plugin instance."""
+    return LikeC4Plugin()
+
+
+@pytest.fixture
+def docs_dir(tmp_path):
+    """Create a temporary docs directory."""
+    docs = tmp_path / "docs"
+    docs.mkdir()
+    return docs
+
+
+class TestPluginInit:
+    """Tests for plugin initialization."""
+
+    def test_init_defaults(self, plugin):
+        """Test that plugin initializes with correct defaults."""
+        assert plugin.docs_dir is None
+        assert plugin.page_projects == {}
+        assert plugin.project_map == {}
+
+
+class TestDiscoverProjects:
+    """Tests for the _discover_projects method."""
+
+    def test_discover_single_project(self, plugin, docs_dir):
+        """Test discovering a single project."""
+        project_dir = docs_dir / "myproject"
+        project_dir.mkdir()
+        config_file = project_dir / "likec4.config.json"
+        config_file.write_text(json.dumps({"name": "myproject"}))
+
+        plugin._discover_projects(docs_dir)
+
+        assert "myproject" in plugin.project_map
+        assert plugin.project_map["myproject"] == "myproject"
+
+    def test_discover_multiple_projects(self, plugin, docs_dir):
+        """Test discovering multiple projects."""
+        for name in ["project1", "project2", "project3"]:
+            project_dir = docs_dir / name
+            project_dir.mkdir()
+            config_file = project_dir / "likec4.config.json"
+            config_file.write_text(json.dumps({"name": name}))
+
+        plugin._discover_projects(docs_dir)
+
+        assert len(plugin.project_map) == 3
+        assert "project1" in plugin.project_map
+        assert "project2" in plugin.project_map
+        assert "project3" in plugin.project_map
+
+    def test_discover_nested_project(self, plugin, docs_dir):
+        """Test discovering a nested project."""
+        nested_dir = docs_dir / "sub" / "nested"
+        nested_dir.mkdir(parents=True)
+        config_file = nested_dir / "likec4.config.json"
+        config_file.write_text(json.dumps({"name": "nested"}))
+
+        plugin._discover_projects(docs_dir)
+
+        assert "nested" in plugin.project_map
+        assert plugin.project_map["nested"] == "sub/nested"
+
+    def test_discover_no_projects_uses_default(self, plugin, docs_dir):
+        """Test that no projects defaults to root project."""
+        plugin._discover_projects(docs_dir)
+
+        assert None in plugin.project_map
+        assert plugin.project_map[None] == "."
+
+    def test_discover_invalid_json_skipped(self, plugin, docs_dir):
+        """Test that invalid JSON config files are skipped."""
+        project_dir = docs_dir / "badproject"
+        project_dir.mkdir()
+        config_file = project_dir / "likec4.config.json"
+        config_file.write_text("not valid json")
+
+        plugin._discover_projects(docs_dir)
+
+        assert "badproject" not in plugin.project_map
+        # Should fall back to default
+        assert None in plugin.project_map
+
+    def test_discover_config_without_name_skipped(self, plugin, docs_dir):
+        """Test that config without name field is skipped."""
+        project_dir = docs_dir / "noname"
+        project_dir.mkdir()
+        config_file = project_dir / "likec4.config.json"
+        config_file.write_text(json.dumps({"version": "1.0"}))
+
+        plugin._discover_projects(docs_dir)
+
+        assert "noname" not in plugin.project_map
+
+    def test_discover_nonexistent_dir(self, plugin, tmp_path):
+        """Test discovering projects in nonexistent directory."""
+        nonexistent = tmp_path / "nonexistent"
+
+        plugin._discover_projects(nonexistent)
+
+        # Should not raise, project_map remains empty
+        assert plugin.project_map == {}
+
+
+class TestFindNearestProject:
+    """Tests for the _find_nearest_project method."""
+
+    def test_find_project_in_same_directory(self, plugin, docs_dir):
+        """Test finding project when page is in project directory."""
+        plugin.project_map = {"myproject": "myproject"}
+
+        page_path = docs_dir / "myproject" / "index.md"
+        result = plugin._find_nearest_project(page_path, docs_dir)
+
+        assert result == "myproject"
+
+    def test_find_project_in_subdirectory(self, plugin, docs_dir):
+        """Test finding project when page is in subdirectory of project."""
+        plugin.project_map = {"myproject": "myproject"}
+
+        page_path = docs_dir / "myproject" / "sub" / "page.md"
+        result = plugin._find_nearest_project(page_path, docs_dir)
+
+        assert result == "myproject"
+
+    def test_find_no_project_returns_none(self, plugin, docs_dir):
+        """Test that pages outside projects return None."""
+        plugin.project_map = {"myproject": "myproject"}
+
+        page_path = docs_dir / "other" / "page.md"
+        result = plugin._find_nearest_project(page_path, docs_dir)
+
+        assert result is None
+
+    def test_find_root_project(self, plugin, docs_dir):
+        """Test finding root project."""
+        plugin.project_map = {None: "."}
+
+        page_path = docs_dir / "page.md"
+        result = plugin._find_nearest_project(page_path, docs_dir)
+
+        assert result is None
+
+
+class TestOnConfig:
+    """Tests for the on_config method."""
+
+    def test_on_config_sets_docs_dir(self, plugin, docs_dir):
+        """Test that on_config sets docs_dir."""
+        config = {"docs_dir": str(docs_dir)}
+
+        result = plugin.on_config(config)
+
+        assert plugin.docs_dir == docs_dir
+        assert result == config
+
+    def test_on_config_discovers_projects(self, plugin, docs_dir):
+        """Test that on_config triggers project discovery."""
+        project_dir = docs_dir / "proj"
+        project_dir.mkdir()
+        config_file = project_dir / "likec4.config.json"
+        config_file.write_text(json.dumps({"name": "proj"}))
+
+        config = {"docs_dir": str(docs_dir)}
+        plugin.on_config(config)
+
+        assert "proj" in plugin.project_map
+
+
+class TestOnPageMarkdown:
+    """Tests for the on_page_markdown method."""
+
+    def test_replaces_code_block(self, plugin, docs_dir):
+        """Test that likec4-view code blocks are replaced."""
+        plugin.docs_dir = docs_dir
+        plugin.project_map = {None: "."}
+
+        page = MagicMock()
+        page.file.src_uri = "index.md"
+        page.file.src_path = "index.md"
+
+        markdown = """# Title
+
+```likec4-view
+my-view
+```
+
+Some text."""
+
+        result = plugin.on_page_markdown(markdown, page)
+
+        assert "```likec4-view" not in result
+        assert '<likec4-view view-id="my-view"' in result
+        assert "Some text." in result
+
+    def test_replaces_multiple_code_blocks(self, plugin, docs_dir):
+        """Test that multiple code blocks are replaced."""
+        plugin.docs_dir = docs_dir
+        plugin.project_map = {None: "."}
+
+        page = MagicMock()
+        page.file.src_uri = "index.md"
+        page.file.src_path = "index.md"
+
+        markdown = """```likec4-view
+view1
+```
+
+```likec4-view
+view2
+```"""
+
+        result = plugin.on_page_markdown(markdown, page)
+
+        assert 'view-id="view1"' in result
+        assert 'view-id="view2"' in result
+
+    def test_tracks_projects_on_page(self, plugin, docs_dir):
+        """Test that projects used on page are tracked."""
+        plugin.docs_dir = docs_dir
+        plugin.project_map = {"proj": "proj"}
+
+        page = MagicMock()
+        page.file.src_uri = "proj/index.md"
+        page.file.src_path = "proj/index.md"
+
+        markdown = """```likec4-view
+my-view
+```"""
+
+        plugin.on_page_markdown(markdown, page)
+
+        assert "proj/index.md" in plugin.page_projects
+        assert "proj" in plugin.page_projects["proj/index.md"]
+
+    def test_preserves_non_likec4_content(self, plugin, docs_dir):
+        """Test that non-likec4 content is preserved."""
+        plugin.docs_dir = docs_dir
+        plugin.project_map = {None: "."}
+
+        page = MagicMock()
+        page.file.src_uri = "index.md"
+        page.file.src_path = "index.md"
+
+        markdown = """# Title
+
+```python
+print("hello")
+```
+
+Some text."""
+
+        result = plugin.on_page_markdown(markdown, page)
+
+        assert result == markdown
+
+
+class TestOnPageContent:
+    """Tests for the on_page_content method."""
+
+    def test_injects_script_for_page_with_views(self, plugin):
+        """Test that script tags are injected for pages with views."""
+        plugin.page_projects = {"index.md": {None}}
+
+        page = MagicMock()
+        page.file.src_uri = "index.md"
+        page.url = "index.html"
+
+        html = "<h1>Title</h1>"
+        result = plugin.on_page_content(html, page)
+
+        assert "<script" in result
+        assert "likec4_views.js" in result
+        assert "<h1>Title</h1>" in result
+
+    def test_no_script_for_page_without_views(self, plugin):
+        """Test that no script is injected for pages without views."""
+        plugin.page_projects = {}
+
+        page = MagicMock()
+        page.file.src_uri = "other.md"
+        page.url = "other.html"
+
+        html = "<h1>Title</h1>"
+        result = plugin.on_page_content(html, page)
+
+        assert result == html
+
+    def test_injects_multiple_scripts_for_multiple_projects(self, plugin):
+        """Test that multiple scripts are injected for multiple projects."""
+        plugin.page_projects = {"index.md": {"proj1", "proj2"}}
+
+        page = MagicMock()
+        page.file.src_uri = "index.md"
+        page.url = "index.html"
+
+        html = "<h1>Title</h1>"
+        result = plugin.on_page_content(html, page)
+
+        assert "likec4_views_proj1.js" in result
+        assert "likec4_views_proj2.js" in result
+
+
+class TestOnPostBuild:
+    """Tests for the on_post_build method."""
+
+    @patch("mkdocs_likec4.plugin.WebComponentGenerator.generate")
+    def test_generates_for_all_used_projects(self, mock_generate, plugin, tmp_path):
+        """Test that web components are generated for all used projects."""
+        plugin.docs_dir = tmp_path / "docs"
+        plugin.docs_dir.mkdir()
+        plugin.project_map = {"proj1": "proj1", "proj2": "proj2"}
+        plugin.page_projects = {
+            "page1.md": {"proj1"},
+            "page2.md": {"proj2"},
+        }
+
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+        config = {"site_dir": str(site_dir)}
+
+        plugin.on_post_build(config)
+
+        assert mock_generate.call_count == 2
+
+    @patch("mkdocs_likec4.plugin.WebComponentGenerator.generate")
+    def test_skips_undiscovered_projects(self, mock_generate, plugin, tmp_path):
+        """Test that undiscovered projects are skipped."""
+        plugin.docs_dir = tmp_path / "docs"
+        plugin.docs_dir.mkdir()
+        plugin.project_map = {"proj1": "proj1"}
+        plugin.page_projects = {
+            "page1.md": {"proj1", "unknown"},
+        }
+
+        site_dir = tmp_path / "site"
+        site_dir.mkdir()
+        config = {"site_dir": str(site_dir)}
+
+        plugin.on_post_build(config)
+
+        # Only proj1 should be generated
+        assert mock_generate.call_count == 1
+        call_args = mock_generate.call_args[0]
+        assert call_args[0] == "proj1"