mkdocs-zip-bundle-plugin 0.1.0__tar.gz

mkdocs_zip_bundle_plugin-0.1.0/LICENSE

@@ -0,0 +1,33 @@
+MIT License
+
+Copyright (c) 2026 Daemonless
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+This package bundles JSZip v3.10.1, which includes pako.
+
+JSZip is copyright (c) 2009-2016 Stuart Knightley <stuart@stuartk.com>
+Dual licensed under the MIT License or GPLv3.
+Source: https://github.com/Stuk/jszip
+
+pako is copyright (c) 2014-2017 by Vitaly Puzrin and Andrei Tuputcyn
+Licensed under the MIT License.
+Source: https://github.com/nodeca/pako

mkdocs_zip_bundle_plugin-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mkdocs-zip-bundle-plugin
+Version: 0.1.0
+Summary: A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file.
+Author: Daemonless
+License: MIT
+Project-URL: Homepage, https://github.com/daemonless/mkdocs-zip-bundle-plugin
+Project-URL: Repository, https://github.com/daemonless/mkdocs-zip-bundle-plugin
+Project-URL: Bug Tracker, https://github.com/daemonless/mkdocs-zip-bundle-plugin/issues
+Keywords: mkdocs,zip,bundle,placeholders,interactive
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: beautifulsoup4>=4.11.0
+Dynamic: license-file
+
+# mkdocs-zip-bundle-plugin
+
+A MkDocs plugin that turns code blocks into downloadable files. Tag any code block with a bundle ID and filename — the plugin injects a download button automatically. Works with single files (direct download) or multiple files (ZIP archive).
+
+Built to pair with [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin): if your docs use interactive placeholders like `@PORT@`, the downloaded file will contain the user's actual values, not the defaults.
+
+## Features
+
+- **Single file downloads** — one code block gets a direct raw file download, no ZIP needed
+- **Multi-file ZIP bundles** — group multiple code blocks into one ZIP with a single button
+- **Placeholder-aware** — captures the live browser state, so user-edited values are included in the download
+- **Nested paths** — use `configs/app.yaml` as a filename to create subdirectories inside the ZIP
+- **Custom button labels** — override auto-generated text per bundle
+- **Self-contained** — ships with JSZip and default styling, no extra dependencies
+
+## Installation
+
+```bash
+pip install mkdocs-zip-bundle-plugin
+```
+
+Requires Python 3.8+ and MkDocs 1.4+. Download buttons require a modern browser (Chrome, Firefox, Safari, Edge).
+
+## Configuration
+
+```yaml
+plugins:
+  - search
+  - zip-bundle:
+      include_jszip: true   # set to false if you already load JSZip elsewhere
+      zip_label_suffix: "(.zip)"  # appended to multi-file bundle button labels
+```
+
+Also enable the `attr_list` extension so MkDocs can read attributes on code blocks:
+
+```yaml
+markdown_extensions:
+  - attr_list
+  - pymdownx.superfences  # recommended for reliable attribute support
+```
+
+## Usage
+
+Add `data-zip-bundle` and `data-zip-filename` attributes to any fenced code block:
+
+### Single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+The plugin injects a **Download compose.yaml** button directly after the code block.
+
+### Multiple files (ZIP)
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="setup.sh" }
+    mkdir -p /data/app
+    ```
+
+Both blocks share the same bundle ID. The plugin injects a single **Download My App (.zip)** button after the last block.
+
+### Custom button label
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-label="Download config" }
+    ...
+    ```
+
+### Force ZIP for a single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-force="true" }
+    ...
+    ```
+
+### Nested directories
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="config/app.yaml" }
+    ...
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="scripts/setup.sh" }
+    ...
+    ```
+
+The ZIP will contain `config/app.yaml` and `scripts/setup.sh` preserving the directory structure.
+
+## How it works with placeholders
+
+If you use [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin), your docs can have editable values like `@PORT@` or `@DATA_PATH@` that users customize in the browser.
+
+When the user clicks a download button from this plugin, the downloaded file contains whatever is currently in the code block — including any values the user has already changed. This makes it possible to offer personalized, copy-paste-ready config files directly from your documentation.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details. Bundles [JSZip](https://github.com/Stuk/jszip) (MIT).

mkdocs_zip_bundle_plugin-0.1.0/README.md

@@ -0,0 +1,102 @@
+# mkdocs-zip-bundle-plugin
+
+A MkDocs plugin that turns code blocks into downloadable files. Tag any code block with a bundle ID and filename — the plugin injects a download button automatically. Works with single files (direct download) or multiple files (ZIP archive).
+
+Built to pair with [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin): if your docs use interactive placeholders like `@PORT@`, the downloaded file will contain the user's actual values, not the defaults.
+
+## Features
+
+- **Single file downloads** — one code block gets a direct raw file download, no ZIP needed
+- **Multi-file ZIP bundles** — group multiple code blocks into one ZIP with a single button
+- **Placeholder-aware** — captures the live browser state, so user-edited values are included in the download
+- **Nested paths** — use `configs/app.yaml` as a filename to create subdirectories inside the ZIP
+- **Custom button labels** — override auto-generated text per bundle
+- **Self-contained** — ships with JSZip and default styling, no extra dependencies
+
+## Installation
+
+```bash
+pip install mkdocs-zip-bundle-plugin
+```
+
+Requires Python 3.8+ and MkDocs 1.4+. Download buttons require a modern browser (Chrome, Firefox, Safari, Edge).
+
+## Configuration
+
+```yaml
+plugins:
+  - search
+  - zip-bundle:
+      include_jszip: true   # set to false if you already load JSZip elsewhere
+      zip_label_suffix: "(.zip)"  # appended to multi-file bundle button labels
+```
+
+Also enable the `attr_list` extension so MkDocs can read attributes on code blocks:
+
+```yaml
+markdown_extensions:
+  - attr_list
+  - pymdownx.superfences  # recommended for reliable attribute support
+```
+
+## Usage
+
+Add `data-zip-bundle` and `data-zip-filename` attributes to any fenced code block:
+
+### Single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+The plugin injects a **Download compose.yaml** button directly after the code block.
+
+### Multiple files (ZIP)
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="setup.sh" }
+    mkdir -p /data/app
+    ```
+
+Both blocks share the same bundle ID. The plugin injects a single **Download My App (.zip)** button after the last block.
+
+### Custom button label
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-label="Download config" }
+    ...
+    ```
+
+### Force ZIP for a single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-force="true" }
+    ...
+    ```
+
+### Nested directories
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="config/app.yaml" }
+    ...
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="scripts/setup.sh" }
+    ...
+    ```
+
+The ZIP will contain `config/app.yaml` and `scripts/setup.sh` preserving the directory structure.
+
+## How it works with placeholders
+
+If you use [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin), your docs can have editable values like `@PORT@` or `@DATA_PATH@` that users customize in the browser.
+
+When the user clicks a download button from this plugin, the downloaded file contains whatever is currently in the code block — including any values the user has already changed. This makes it possible to offer personalized, copy-paste-ready config files directly from your documentation.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details. Bundles [JSZip](https://github.com/Stuk/jszip) (MIT).

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle/__init__.py

@@ -0,0 +1 @@
+# mkdocs-zip-bundle-plugin

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle/plugin.py

@@ -0,0 +1,147 @@
+"""
+MkDocs plugin to bundle specific code blocks into downloadable ZIP or raw files.
+"""
+import os
+import logging
+import shutil
+import re
+from mkdocs.plugins import BasePlugin
+from mkdocs.config import config_options
+from bs4 import BeautifulSoup
+
+log = logging.getLogger('mkdocs.plugins.zip_bundle')
+
+class ZipBundlePlugin(BasePlugin):
+    """
+    Plugin class for bundling code blocks.
+    """
+    config_scheme = (
+        ('include_jszip', config_options.Type(bool, default=True)),
+        ('zip_label_suffix', config_options.Type(str, default="(.zip)")),
+    )
+
+    def on_config(self, config):
+        """
+        Automatically add our JS and CSS to the project configuration.
+        """
+        if self.config['include_jszip']:
+            js_jszip = 'javascripts/jszip.min.js'
+            if js_jszip not in config['extra_javascript']:
+                config['extra_javascript'].append(js_jszip)
+
+        js_bundle = 'javascripts/zip-bundle.js'
+        if js_bundle not in config['extra_javascript']:
+            config['extra_javascript'].append(js_bundle)
+
+        css_bundle = 'css/zip-bundle.css'
+        if css_bundle not in config['extra_css']:
+            config['extra_css'].append(css_bundle)
+
+        return config
+
+    def _sanitize_filename(self, filename):
+        """
+        Sanitize filename to prevent path traversal while allowing subdirectories.
+        """
+        # Replace backslashes with forward slashes for ZIP compatibility
+        filename = filename.replace('\\', '/')
+        # Remove any ".." segments to prevent traversal
+        filename = re.sub(r'\.\.(?=/|$)', '', filename)
+        # Remove any leading slashes
+        filename = re.sub(r'^/+', '', filename)
+        # Collapse multiple slashes
+        filename = re.sub(r'/+', '/', filename)
+        return filename.strip()
+
+    def _create_button(self, soup, bundle_id, elements):
+        """
+        Create the download button for a bundle.
+        """
+        btn = soup.new_tag("button")
+        btn['class'] = "md-button zip-bundle-btn"
+        btn['data-bundle-id'] = bundle_id
+        btn['type'] = "button"
+        btn['aria-label'] = f"Download {bundle_id.replace('-', ' ')} bundle"
+
+        # Check for custom label on ANY element in the bundle (first one wins)
+        custom_label = next((el.get('data-zip-label') for el in elements if el.get('data-zip-label')), None)
+        force_zip = any(el.get('data-zip-force') == 'true' for el in elements)
+
+        if custom_label:
+            btn.string = custom_label
+        elif len(elements) == 1 and not force_zip:
+            filename = elements[0].get('data-zip-filename', 'file')
+            # Extract only the base filename for the button label if it's a path
+            display_name = os.path.basename(filename)
+            btn.string = f"Download {display_name}"
+        else:
+            label = bundle_id.replace('-', ' ').title()
+            suffix = self.config['zip_label_suffix']
+            btn.string = f"Download {label} {suffix}".strip()
+
+        container = soup.new_tag("div")
+        container['class'] = "zip-bundle-container"
+        container.append(btn)
+        return container
+
+    def on_page_content(self, html, page, config, files):
+        """
+        Inject download buttons into the page content.
+        """
+        if "data-zip-bundle" not in html:
+            return html
+
+        soup = BeautifulSoup(html, 'html.parser')
+
+        # 1. Group all elements by their bundle ID
+        bundles = {}
+        for el in soup.find_all(attrs={"data-zip-bundle": True}):
+            bundle_id = el['data-zip-bundle']
+            if bundle_id not in bundles:
+                bundles[bundle_id] = []
+            
+            # Sanitize filename on the element before grouping
+            if el.has_attr('data-zip-filename'):
+                el['data-zip-filename'] = self._sanitize_filename(el['data-zip-filename'])
+            
+            bundles[bundle_id].append(el)
+
+        if not bundles:
+            return html
+
+        # 2. For each bundle, inject a download button after the last element
+        for bundle_id, elements in bundles.items():
+            container = self._create_button(soup, bundle_id, elements)
+            elements[-1].insert_after(container)
+
+        return str(soup)
+
+    def on_post_build(self, config):
+        """
+        Copy assets to the site directory after build.
+        """
+        assets_dir = os.path.join(os.path.dirname(__file__), 'assets')
+        
+        to_copy = ['zip-bundle.js', 'zip-bundle.css']
+        if self.config['include_jszip']:
+            to_copy.append('jszip.min.js')
+
+        for filename in to_copy:
+            subfolder = 'javascripts' if filename.endswith('.js') else 'css'
+            dest_path = os.path.join(config['site_dir'], subfolder, filename)
+            src_path = os.path.join(assets_dir, filename)
+
+            if not os.path.exists(src_path):
+                raise FileNotFoundError(
+                    f"ZipBundle: Asset '{filename}' not found in package at {src_path}. "
+                    "Your installation may be corrupt — try reinstalling mkdocs-zip-bundle."
+                )
+
+            try:
+                os.makedirs(os.path.dirname(dest_path), exist_ok=True)
+                shutil.copyfile(src_path, dest_path)
+            except OSError as e:
+                raise OSError(
+                    f"ZipBundle: Failed to copy '{filename}' to {dest_path}: {e}. "
+                    "Downloads will not work in the built site."
+                ) from e

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mkdocs-zip-bundle-plugin
+Version: 0.1.0
+Summary: A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file.
+Author: Daemonless
+License: MIT
+Project-URL: Homepage, https://github.com/daemonless/mkdocs-zip-bundle-plugin
+Project-URL: Repository, https://github.com/daemonless/mkdocs-zip-bundle-plugin
+Project-URL: Bug Tracker, https://github.com/daemonless/mkdocs-zip-bundle-plugin/issues
+Keywords: mkdocs,zip,bundle,placeholders,interactive
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mkdocs>=1.4.0
+Requires-Dist: beautifulsoup4>=4.11.0
+Dynamic: license-file
+
+# mkdocs-zip-bundle-plugin
+
+A MkDocs plugin that turns code blocks into downloadable files. Tag any code block with a bundle ID and filename — the plugin injects a download button automatically. Works with single files (direct download) or multiple files (ZIP archive).
+
+Built to pair with [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin): if your docs use interactive placeholders like `@PORT@`, the downloaded file will contain the user's actual values, not the defaults.
+
+## Features
+
+- **Single file downloads** — one code block gets a direct raw file download, no ZIP needed
+- **Multi-file ZIP bundles** — group multiple code blocks into one ZIP with a single button
+- **Placeholder-aware** — captures the live browser state, so user-edited values are included in the download
+- **Nested paths** — use `configs/app.yaml` as a filename to create subdirectories inside the ZIP
+- **Custom button labels** — override auto-generated text per bundle
+- **Self-contained** — ships with JSZip and default styling, no extra dependencies
+
+## Installation
+
+```bash
+pip install mkdocs-zip-bundle-plugin
+```
+
+Requires Python 3.8+ and MkDocs 1.4+. Download buttons require a modern browser (Chrome, Firefox, Safari, Edge).
+
+## Configuration
+
+```yaml
+plugins:
+  - search
+  - zip-bundle:
+      include_jszip: true   # set to false if you already load JSZip elsewhere
+      zip_label_suffix: "(.zip)"  # appended to multi-file bundle button labels
+```
+
+Also enable the `attr_list` extension so MkDocs can read attributes on code blocks:
+
+```yaml
+markdown_extensions:
+  - attr_list
+  - pymdownx.superfences  # recommended for reliable attribute support
+```
+
+## Usage
+
+Add `data-zip-bundle` and `data-zip-filename` attributes to any fenced code block:
+
+### Single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+The plugin injects a **Download compose.yaml** button directly after the code block.
+
+### Multiple files (ZIP)
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" }
+    services:
+      app:
+        image: my-image:latest
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="setup.sh" }
+    mkdir -p /data/app
+    ```
+
+Both blocks share the same bundle ID. The plugin injects a single **Download My App (.zip)** button after the last block.
+
+### Custom button label
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-label="Download config" }
+    ...
+    ```
+
+### Force ZIP for a single file
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="compose.yaml" data-zip-force="true" }
+    ...
+    ```
+
+### Nested directories
+
+    ```yaml { data-zip-bundle="my-app" data-zip-filename="config/app.yaml" }
+    ...
+    ```
+
+    ```bash { data-zip-bundle="my-app" data-zip-filename="scripts/setup.sh" }
+    ...
+    ```
+
+The ZIP will contain `config/app.yaml` and `scripts/setup.sh` preserving the directory structure.
+
+## How it works with placeholders
+
+If you use [`mkdocs-placeholder-plugin`](https://github.com/six-two/mkdocs-placeholder-plugin), your docs can have editable values like `@PORT@` or `@DATA_PATH@` that users customize in the browser.
+
+When the user clicks a download button from this plugin, the downloaded file contains whatever is currently in the code block — including any values the user has already changed. This makes it possible to offer personalized, copy-paste-ready config files directly from your documentation.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details. Bundles [JSZip](https://github.com/Stuk/jszip) (MIT).

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+LICENSE
+README.md
+pyproject.toml
+mkdocs_zip_bundle/__init__.py
+mkdocs_zip_bundle/plugin.py
+mkdocs_zip_bundle_plugin.egg-info/PKG-INFO
+mkdocs_zip_bundle_plugin.egg-info/SOURCES.txt
+mkdocs_zip_bundle_plugin.egg-info/dependency_links.txt
+mkdocs_zip_bundle_plugin.egg-info/entry_points.txt
+mkdocs_zip_bundle_plugin.egg-info/requires.txt
+mkdocs_zip_bundle_plugin.egg-info/top_level.txt
+tests/test_integration.py
+tests/test_plugin.py

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+zip-bundle = mkdocs_zip_bundle.plugin:ZipBundlePlugin

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/requires.txt

@@ -0,0 +1,2 @@
+mkdocs>=1.4.0
+beautifulsoup4>=4.11.0

mkdocs_zip_bundle_plugin-0.1.0/mkdocs_zip_bundle_plugin.egg-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_zip_bundle

mkdocs_zip_bundle_plugin-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mkdocs-zip-bundle-plugin"
+version = "0.1.0"
+description = "A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file."
+readme = "README.md"
+authors = [{ name = "Daemonless" }]
+license = { text = "MIT" }
+requires-python = ">=3.8"
+keywords = ["mkdocs", "zip", "bundle", "placeholders", "interactive"]
+dependencies = [
+    "mkdocs>=1.4.0",
+    "beautifulsoup4>=4.11.0"
+]
+
+[project.urls]
+Homepage = "https://github.com/daemonless/mkdocs-zip-bundle-plugin"
+Repository = "https://github.com/daemonless/mkdocs-zip-bundle-plugin"
+"Bug Tracker" = "https://github.com/daemonless/mkdocs-zip-bundle-plugin/issues"
+
+[project.entry-points."mkdocs.plugins"]
+zip-bundle = "mkdocs_zip_bundle.plugin:ZipBundlePlugin"

mkdocs_zip_bundle_plugin-0.1.0/setup.cfg

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

mkdocs_zip_bundle_plugin-0.1.0/tests/test_integration.py

@@ -0,0 +1,56 @@
+import pytest
+from bs4 import BeautifulSoup
+from mkdocs_zip_bundle.plugin import ZipBundlePlugin
+
+@pytest.fixture
+def plugin():
+    plugin = ZipBundlePlugin()
+    plugin.config = {
+        'include_jszip': True,
+        'zip_label_suffix': '(.zip)',
+    }
+    return plugin
+
+def test_on_page_content_tabbed_placement(plugin):
+    # MkDocs Material renders fenced code block attributes onto the .highlight wrapper div
+    html = """
+    <div class="tabbed-set">
+        <div class="tabbed-content">
+            <div class="tabbed-block">
+                <div class="highlight" data-zip-bundle="b1" data-zip-filename="f1.txt">
+                    <pre><code>content</code></pre>
+                </div>
+            </div>
+        </div>
+    </div>
+    """
+    result = plugin.on_page_content(html, None, None, None)
+    soup = BeautifulSoup(result, 'html.parser')
+
+    # Button should be INSIDE the tabbed-block, right after the highlight div
+    tabbed_block = soup.find(class_='tabbed-block')
+    button_container = soup.find(class_='zip-bundle-container')
+
+    assert button_container is not None
+    assert button_container.parent == tabbed_block
+
+def test_on_page_content_multi_bundle(plugin):
+    html = """
+    <div data-zip-bundle="b1" data-zip-filename="f1.txt"></div>
+    <div data-zip-bundle="b2" data-zip-filename="f2.txt"></div>
+    """
+    result = plugin.on_page_content(html, None, None, None)
+    soup = BeautifulSoup(result, 'html.parser')
+    
+    buttons = soup.find_all(class_='zip-bundle-btn')
+    assert len(buttons) == 2
+    assert buttons[0]['data-bundle-id'] == 'b1'
+    assert buttons[1]['data-bundle-id'] == 'b2'
+
+def test_on_config_asset_injection(plugin):
+    config = {'extra_javascript': [], 'extra_css': []}
+    result = plugin.on_config(config)
+    
+    assert 'javascripts/jszip.min.js' in result['extra_javascript']
+    assert 'javascripts/zip-bundle.js' in result['extra_javascript']
+    assert 'css/zip-bundle.css' in result['extra_css']

mkdocs_zip_bundle_plugin-0.1.0/tests/test_plugin.py

@@ -0,0 +1,126 @@
+import os
+import shutil
+import tempfile
+import pytest
+from unittest.mock import patch
+from bs4 import BeautifulSoup
+from mkdocs_zip_bundle.plugin import ZipBundlePlugin
+
+
+@pytest.fixture
+def plugin():
+    plugin = ZipBundlePlugin()
+    plugin.config = {
+        'include_jszip': True,
+        'zip_label_suffix': '(.zip)',
+    }
+    return plugin
+
+
+def make_element(soup, attrs):
+    """Create a real BS4 Tag with the given attributes."""
+    tag = soup.new_tag("div")
+    for k, v in attrs.items():
+        tag[k] = v
+    return tag
+
+
+# --- _sanitize_filename ---
+
+def test_sanitize_filename(plugin):
+    assert plugin._sanitize_filename('test.txt') == 'test.txt'
+    assert plugin._sanitize_filename('/abs/path/test.txt') == 'abs/path/test.txt'
+    assert plugin._sanitize_filename('../traversal.txt') == 'traversal.txt'
+    assert plugin._sanitize_filename('some/../../path.txt') == 'some/path.txt'
+    assert plugin._sanitize_filename('win\\path.txt') == 'win/path.txt'
+    assert plugin._sanitize_filename('subdir/file.txt') == 'subdir/file.txt'
+    assert plugin._sanitize_filename('//double//slash//') == 'double/slash/'
+
+
+# --- _create_button ---
+
+def test_create_button_single(plugin):
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {'data-zip-filename': 'compose.yaml'})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Download compose.yaml'
+    assert button.get('type') == 'button'
+    assert 'onclick' not in button.attrs
+
+
+def test_create_button_single_subdir(plugin):
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {'data-zip-filename': 'configs/compose.yaml'})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Download compose.yaml'
+
+
+def test_create_button_custom_label(plugin):
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {'data-zip-filename': 'f.txt', 'data-zip-label': 'Grab Files'})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Grab Files'
+
+
+def test_create_button_multi(plugin):
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {}), make_element(soup, {})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Download My Bundle (.zip)'
+
+
+def test_create_button_force_zip_single(plugin):
+    """Single file with data-zip-force=true should use ZIP label."""
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {'data-zip-filename': 'f.txt', 'data-zip-force': 'true'})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Download My Bundle (.zip)'
+
+
+# --- on_post_build ---
+
+@pytest.fixture
+def assets_dir():
+    return os.path.join(os.path.dirname(__file__), '..', 'mkdocs_zip_bundle', 'assets')
+
+
+def test_on_post_build_copies_assets(plugin, tmp_path):
+    config = {'site_dir': str(tmp_path)}
+    plugin.on_post_build(config)
+
+    assert (tmp_path / 'javascripts' / 'jszip.min.js').exists()
+    assert (tmp_path / 'javascripts' / 'zip-bundle.js').exists()
+    assert (tmp_path / 'css' / 'zip-bundle.css').exists()
+
+
+def test_on_post_build_skips_jszip_when_disabled(plugin, tmp_path):
+    plugin.config['include_jszip'] = False
+    config = {'site_dir': str(tmp_path)}
+    plugin.on_post_build(config)
+
+    assert not (tmp_path / 'javascripts' / 'jszip.min.js').exists()
+    assert (tmp_path / 'javascripts' / 'zip-bundle.js').exists()
+
+
+def test_on_post_build_missing_asset_raises(plugin, tmp_path):
+    config = {'site_dir': str(tmp_path)}
+    with patch('os.path.exists', return_value=False):
+        with pytest.raises(FileNotFoundError, match='ZipBundle'):
+            plugin.on_post_build(config)
+
+
+def test_on_post_build_copy_failure_raises(plugin, tmp_path):
+    config = {'site_dir': str(tmp_path)}
+    with patch('shutil.copyfile', side_effect=OSError("disk full")):
+        with pytest.raises(OSError, match='ZipBundle'):
+            plugin.on_post_build(config)