Merge pull request #4 from atteggiani/3-add_prefix_input

Added prefix input and tests

Author: foosel

.github/workflows/build.yml

@@ -18,10 +18,10 @@ jobs:
           python-version: "3.11"
       - name: 🏗 Install build dependencies
         run: |
-          python -m pip install wheel --user
+          python -m pip install build --user
       - name: 🔨 Build a binary wheel and a source tarball
         run: |
-          python setup.py sdist bdist_wheel
+          python -m build
       - name: ⬆ Upload build result
         uses: actions/upload-artifact@v4
         with:
@@ -39,17 +39,34 @@ jobs:
           python-version: "3.11"
       - name: 🏗 Set up dev dependencies
         run: |
-          pip install pre-commit
+          pip install -r requirements-dev.txt
       - name: 🚀 Run pre-commit
         run: |
           pre-commit run --all-files --show-diff-on-failure
 
+  test:
+    name: 🧪 Run tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: 🏗 Set up Python 3.11
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: 🏗 Set up dev dependencies
+        run: |
+          pip install -r requirements-dev.txt
+      - name: 🚀 Run pytest
+        run: |
+          pytest
+
   publish-on-pypi:
     name: 📦 Publish tagged releases to PyPI
     if: github.event_name == 'release' && github.repository == 'OctoPrint/mkdocs-site-urls'
     needs:
       - build
       - pre-commit
+      - test
     runs-on: ubuntu-latest
     environment: release
     permissions:

.pre-commit-config.yaml

@@ -1,5 +1,5 @@
 default_language_version:
-  python: python3.11
+  python: python3
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.4.0

README.md

@@ -55,11 +55,34 @@ plugins:
 Be advised that in case of any customization on your part you need to include the default attributes as well if you want
 to keep them, as the default list will not be included automatically anymore.
 
+If `site:` as the prefix does not work for you for any reason, you can also configure that,
+e.g.
+
+```yaml
+plugins:
+  - site-urls:
+      prefix: "relative:"
+```
+
+This can also be used to interpret absolute URLs like `/example/file.png` as relative,
+by setting the `prefix` to `/`.
+
 ## How it works
 
 The plugin hooks into the [`on_page_content` event](https://www.mkdocs.org/dev-guide/plugins/#on_page_content)
 and replaces all URLs in the configured attributes (by default `href`, `src` or `data`) in the rendered HTML with the corresponding site-relative URLs.
 
+## Development
+
+1. Create a venv & activate it, e.g. `python -m venv venv && source venv/bin/activate`
+2. Install the dev requirements: `pip install -r requirements-dev.txt`
+3. Install the `pre-commit` hooks: `pre-commit install`
+
+You can run the tests with `pytest`.
+
+To build the docs, install their dependencies as well (`pip install -r requirements-docs.txt`),
+then run `mkdocs build`.
+
 ## License
 
 This project is licensed under the MIT license, see the [LICENSE](https://github.com/OctoPrint/mkdocs-site-urls/blob/main/LICENSE) file for details.

mkdocs_site_urls/__init__.py

@@ -8,34 +8,41 @@
 logger = mkdocs.plugins.get_plugin_logger(__name__)
 
 
-class SiteUrlsConfig(mkdocs.config.base.Config):
+class Config(mkdocs.config.base.Config):
     attributes = c.Type(list, default=["href", "src", "data"])
-
-
-class SiteUrlsPlugin(mkdocs.plugins.BasePlugin[SiteUrlsConfig]):
-    def on_pre_build(self, *, config: MkDocsConfig) -> None:
-        self._regex = re.compile(
-            r"(" + "|".join(self.config["attributes"]) + r')="site:([^"]+)"',
-            re.IGNORECASE,
-        )
+    prefix = c.Type(str, default="site:")
+
+
+class SiteUrlsPlugin(mkdocs.plugins.BasePlugin[Config]):
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
+        attributes = (re.escape(attr) for attr in self.config["attributes"])
+        self.prefix = re.escape(self.config["prefix"])
+        regex_parts = [
+            r"(",  # capturing group 1
+            "|".join(attributes),  # attributes
+            r")",  # end of capturing group 1
+            r"\s*=\s*",  # equals sign with optional whitespace
+            r"([\"'])",  # quote with capturing group 2
+            self.prefix,  # url prefix
+            r"([^\"']*)",  # remainder of the url with capturing group 3
+            r"\2",  # matching quote
+        ]
+        regex = "".join(regex_parts)
+        self._regex = re.compile(regex, re.IGNORECASE)
+        return config
 
     @mkdocs.plugins.event_priority(50)
     def on_page_content(self, html, page, config, files):
         site_url = config["site_url"]
+        if not site_url.endswith("/"):
+            site_url += "/"
         path = urllib.parse.urlparse(site_url).path
 
-        if not path:
-            path = "/"
-        if not path.endswith("/"):
-            path += "/"
-
         def _replace(match):
-            param = match.group(1)
-            url = match.group(2)
-            if url.startswith("/"):
-                url = url[1:]
+            attribute = match.group(1)
+            url = match.group(3)
 
-            logger.info(f"Replacing site:{match.group(2)} with {path}{url}")
-            return f'{param}="{path}{url}"'
+            logger.info(f"Replacing '{self.prefix}{url}' with '{path}{url}'")
+            return f'{attribute}="{path}{url}"'
 
         return self._regex.sub(_replace, html)

requirements-dev.txt

@@ -0,0 +1,4 @@
+mkdocs>=1.5.0
+pre-commit
+pytest
+-e .

setup.cfg

@@ -1,9 +1,6 @@
 [metadata]
 license_file = LICENSE
 
-[bdist_wheel]
-universal = 1
-
 [flake8]
 max-line-length = 90
 extend-ignore = E203, E231, E265, E266, E402, E501, E731, B023, B903, B904, B907, B950, W503

tests/__init__.py

@@ -0,0 +1,154 @@
+import re
+from unittest.mock import MagicMock
+
+import pytest
+
+from mkdocs_site_urls import SiteUrlsPlugin
+
+
+@pytest.fixture
+def mock_plugin_config():
+    return {"attributes": ["src", "href"], "prefix": "site:"}
+
+
+@pytest.fixture
+def create_plugin(mock_plugin_config):
+    """Factory function to create the plugin with the prescribed configuration options."""
+
+    def _plugin(config=mock_plugin_config, **kwargs):
+        plugin = SiteUrlsPlugin()
+        plugin.load_config(config)
+        for key, value in kwargs.items():
+            setattr(plugin, key, value)
+        return plugin
+
+    return _plugin
+
+
+@pytest.mark.parametrize(
+    "attributes, prefix, string_to_match, match_group1, match_group3, should_match",
+    [
+        (
+            ["href", "src"],
+            "/docs/",
+            'src = "/docs/image.png"',
+            "src",
+            "image.png",
+            True,
+        ),  # valid1
+        (
+            ["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"],
+            "/docs/",
+            'src = "/image.png"',
+            None,
+            None,
+            False,
+        ),  # invalid_different_prefix
+        (
+            ["href", "src"],
+            "/",
+            "href ='site:docs/image.png'",
+            None,
+            None,
+            False,
+        ),  # invalid_different_prefix2
+        (
+            ["data"],
+            "/",
+            "href='/image.png'",
+            None,
+            None,
+            False,
+        ),  # invalid_different_attribute
+    ],
+    ids=[
+        "valid1",
+        "valid2",
+        "valid3",
+        "invalid_different_prefix",
+        "invalid_different_prefix2",
+        "invalid_different_attribute",
+    ],
+)
+def test_on_config_sets_regex(
+    create_plugin,
+    attributes,
+    prefix,
+    string_to_match,
+    match_group1,
+    match_group3,
+    should_match,
+):
+    """Test the on_config method of the SiteUrlsPlugin."""
+    plugin_config = {
+        "attributes": attributes,
+        "prefix": prefix,
+    }
+    plugin = create_plugin(plugin_config)
+    plugin.on_config(MagicMock())
+
+    # Check that the regex is compiled
+    assert isinstance(plugin._regex, re.Pattern)
+    match = plugin._regex.search(string_to_match)
+
+    # Check regex is correct
+    if should_match:
+        assert match is not None
+        assert match.group(1) == match_group1
+        assert match.group(3) == match_group3
+    else:
+        assert match is None
+
+
+@pytest.mark.parametrize(
+    "site_url",
+    [
+        "https://example.com/docs/subpage/",
+        "https://example.com/docs/subpage",
+    ],
+    ids=["trailing_slash", "no_trailing_slash"],
+)
+def test_on_page_content(create_plugin, site_url):
+    """Test the on_page_content method of the SiteUrlsPlugin."""
+    plugin = create_plugin(
+        {
+            "attributes": ["src", "data"],
+            "prefix": "prefix",
+        }
+    )
+    page = MagicMock()
+    config = MagicMock()
+    config.__getitem__.side_effect = lambda key: site_url if key == "site_url" else None
+    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" >
+    """
+
+    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" >
+    """
+    assert result == expected_result