fix: add default for unset or empty site_url

Also update the documentation accordingly and add tests.

Closes #5

Author: foosel

.editorconfig

@@ -12,5 +12,5 @@ trim_trailing_whitespace = true
 indent_style = space
 max_line_length = 90
 
-[*.{yaml,yml}]
+[*.{yaml,yml,md}]
 indent_size = 2

README.md

@@ -12,10 +12,11 @@ A MkDocs plugin that adds support for site-relative `site:` URLs.
 
 Example:
 
-| URL | site_url | resulting URL |
-| --- | -------- | ------------- |
-| `site:images/foo.png` | `https://example.com/` | `/images/foo.png` |
-| `site:images/foo.png` | `https://example.com/bar/` | `/bar/images/foo.png` |
+| URL                   | site_url                    | resulting URL          |
+| --------------------- | --------------------------- | ---------------------- |
+| `site:images/foo.png` | `https://example.com/`      | `/images/foo.png`      |
+| `site:images/foo.png` | `https://example.com/path/` | `/path/images/foo.png` |
+| `site:images/foo.png` | unset/empty                 | `/images/foo.png`      |
 
 **Please note**: This plugin requires MkDocs 1.5 or higher.
 
@@ -67,6 +68,9 @@ plugins:
 This can also be used to interpret absolute URLs like `/example/file.png` as relative,
 by setting the `prefix` to `/`.
 
+The plugin will extract the path prefix to use from the [`site_url`](https://www.mkdocs.org/user-guide/configuration/#site_url).
+configured in your `mkdocs.yaml`. If no `site_url` is configured, it will default to using the root path `/`.
+
 ## How it works
 
 The plugin hooks into the [`on_page_content` event](https://www.mkdocs.org/dev-guide/plugins/#on_page_content)

mkdocs.yml

@@ -1,5 +1,5 @@
 site_name: MkDocs Site URLs Plugin
-site_url: !ENV [SITE_URL, "http://127.0.0.1:8000"]
+site_url: !ENV [SITE_URL, null]
 dev_addr: 127.0.0.1:8000
 repo_name: OctoPrint/mkdocs-site-urls
 repo_url: https://github.com/OctoPrint/mkdocs-site-urls

mkdocs_site_urls/__init__.py

@@ -33,7 +33,9 @@ def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
 
     @mkdocs.plugins.event_priority(50)
     def on_page_content(self, html, page, config, files):
-        site_url = config["site_url"]
+        site_url = config.get("site_url")
+        if not site_url:
+            site_url = ""
         if not site_url.endswith("/"):
             site_url += "/"
         path = urllib.parse.urlparse(site_url).path

setup.cfg

@@ -3,7 +3,7 @@ license_file = LICENSE
 
 [flake8]
 max-line-length = 90
-extend-ignore = E203, E231, E265, E266, E402, E501, E731, B023, B903, B904, B907, B950, W503
+extend-ignore = E203, E221, E222, E231, E265, E266, E402, E501, E731, B023, B903, B904, B907, B950, W503
 select = B,C,E,F,W,T4,B9
 
 [isort]

tests/test_mkdocs_site_urls.py

@@ -28,29 +28,29 @@ def _plugin(config=mock_plugin_config, **kwargs):
 @pytest.mark.parametrize(
     "attributes, prefix, string_to_match, match_group1, match_group3, should_match",
     [
+        (
+            ["data"],
+            "site:",
+            "data=   'site:image.png'",
+            "data",
+            "image.png",
+            True,
+        ),  # valid1
         (
             ["href", "src"],
             "/docs/",
             'src = "/docs/image.png"',
             "src",
             "image.png",
             True,
-        ),  # valid1
+        ),  # valid2
         (
             ["href", "src"],
             "/",
             "href ='/docs/image.png'",
             "href",
             "docs/image.png",
             True,
-        ),  # valid2
-        (
-            ["data"],
-            "site:",
-            "data=   'site:image.png'",
-            "data",
-            "image.png",
-            True,
         ),  # valid3
         (
             ["href", "src"],
@@ -117,38 +117,58 @@ def test_on_config_sets_regex(
 
 
 @pytest.mark.parametrize(
-    "site_url",
+    "prefix, site_url, expected_path",
     [
-        "https://example.com/docs/subpage/",
-        "https://example.com/docs/subpage",
+        ("site:", "https://example.com", "/"),
+        ("site:", "https://example.com/docs/subpage/", "/docs/subpage/"),
+        ("site:", "https://example.com/docs/subpage", "/docs/subpage/"),
+        ("site:", None, "/"),
+        ("site:", "", "/"),
+        ("prefix", None, "/"),
+        ("/", "https://example.com/docs/subpage/", "/docs/subpage/"),
+    ],
+    ids=[
+        "basic",
+        "path_trailing_slash",
+        "path_no_trailing_slash",
+        "none_siteurl",
+        "empty_siteurl",
+        "custom_prefix",
+        "slash_as_prefix",
     ],
-    ids=["trailing_slash", "no_trailing_slash"],
 )
-def test_on_page_content(create_plugin, site_url):
+def test_on_page_content(create_plugin, prefix, site_url, expected_path):
     """Test the on_page_content method of the SiteUrlsPlugin."""
     plugin = create_plugin(
         {
-            "attributes": ["src", "data"],
-            "prefix": "prefix",
+            "attributes": ["src", "data", "href"],
+            "prefix": prefix,
         }
     )
     page = MagicMock()
     config = MagicMock()
-    config.__getitem__.side_effect = lambda key: site_url if key == "site_url" else None
+    config.get.side_effect = (
+        lambda key, default=None: site_url
+        if key == "site_url" and site_url is not None
+        else default
+    )
     files = MagicMock()
-    html = """
-    <img src  ="prefixexample.png" alt="Image">
-    <img data =  \'prefix/image.png\'>
-    <img data="site:docs/image.svg" class="example">
-    <img attr  ="prefix/docs/image.png" >
+
+    html = f"""
+    <img src  ="{prefix}example.png" alt="Image">
+    <img data =  \'{prefix}/image.png\'>
+    <img data="{prefix}docs/image.svg" class="example">
+    <img attr  ="{prefix}/docs/image.png" title="this won't get touched, wrong attribute" >
+    <img href = "NOT_A_PREFIX/foo/image.png" title="neither will this, wrong prefix">
     """
 
     plugin.on_config(config)
     result = plugin.on_page_content(html, page, config, files)
-    expected_result = """
-    <img src="/docs/subpage/example.png" alt="Image">
-    <img data="/docs/subpage//image.png">
-    <img data="site:docs/image.svg" class="example">
-    <img attr  ="prefix/docs/image.png" >
+    expected_result = f"""
+    <img src="{expected_path}example.png" alt="Image">
+    <img data="{expected_path}/image.png">
+    <img data="{expected_path}docs/image.svg" class="example">
+    <img attr  ="{prefix}/docs/image.png" title="this won't get touched, wrong attribute" >
+    <img href = "NOT_A_PREFIX/foo/image.png" title="neither will this, wrong prefix">
     """
     assert result == expected_result