mkdocs-zip-bundle-plugin 0.1.0__py3-none-any.whl

mkdocs_zip_bundle/__init__.py

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

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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_zip_bundle/__init__.py,sha256=3jNJ6SfgMi4B6OrY8UlvKUyHSQJcSX7Gs8_MnC7cV7w,27
+mkdocs_zip_bundle/plugin.py,sha256=EGJd_bnC0PIqjTFbkamDfKdr5dcp7X_V0OiSzapA4ZE,5528
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/licenses/LICENSE,sha256=0haqjdG6Ov4T93hkmNLM8l_MGwhdib1qTvc5Wh6YvSE,1427
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/METADATA,sha256=CmsgDFMHiRMjA6mEqwmvmZzYGuZB29qJefOS2wS9N_E,4330
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/entry_points.txt,sha256=LcWQlmvHSbe44XiW7xEcoxAaVuBZXHiWvLv4FG7m90k,71
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/top_level.txt,sha256=MkX8MjVWHidUsmqRAWdNi5P4wi4Wd2L66tV2s9rNTg0,18
+mkdocs_zip_bundle_plugin-0.1.0.dist-info/RECORD,,

mkdocs_zip_bundle_plugin-0.1.0.dist-info/WHEEL

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

mkdocs_zip_bundle_plugin-0.1.0.dist-info/entry_points.txt

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

mkdocs_zip_bundle_plugin-0.1.0.dist-info/licenses/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.dist-info/top_level.txt

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