mkdocs-zip-bundle-plugin 0.1.1__tar.gz → 0.3.0__tar.gz

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: mkdocs-zip-bundle-plugin
-Version: 0.1.1
-Summary: A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file.
+Version: 0.3.0
+Summary: Bundle code blocks into downloadable ZIP or raw files — for MkDocs/Material and Zensical.
 Author: Daemonless
-License: MIT
+License-Expression: 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
+Keywords: mkdocs,material,zensical,zip,bundle,placeholders,interactive
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -17,9 +17,11 @@ 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).
+Turn code blocks into downloadable files — for **MkDocs/Material** and **[Zensical](https://zensical.org)**. Tag any code block with a bundle ID and filename and a download button is injected 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.
+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. _(MkDocs/Material — see [Using with Zensical](https://mkdocs-zip-bundle-plugin.daemonless.io/configuration/#using-with-zensical) for the Zensical caveat.)_
+
+**[Live demo → mkdocs-zip-bundle-plugin.daemonless.io](https://mkdocs-zip-bundle-plugin.daemonless.io)**
 
 ## Features
 

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/README.md

@@ -1,8 +1,10 @@
 # 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).
+Turn code blocks into downloadable files — for **MkDocs/Material** and **[Zensical](https://zensical.org)**. Tag any code block with a bundle ID and filename and a download button is injected 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.
+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. _(MkDocs/Material — see [Using with Zensical](https://mkdocs-zip-bundle-plugin.daemonless.io/configuration/#using-with-zensical) for the Zensical caveat.)_
+
+**[Live demo → mkdocs-zip-bundle-plugin.daemonless.io](https://mkdocs-zip-bundle-plugin.daemonless.io)**
 
 ## Features
 

mkdocs_zip_bundle_plugin-0.3.0/mkdocs_zip_bundle/assets/zip-bundle.js

@@ -0,0 +1,172 @@
+// ── Button injection ──────────────────────────────────────────────────
+// Mirrors the Python plugin's on_page_content / _create_button so the
+// download buttons exist even where the plugin's build hook never runs
+// (e.g. Zensical). Idempotent: skips any bundle that already has a button,
+// so on MkDocs/Material (server-injected) this is a harmless no-op.
+
+function sanitizeFilename(filename) {
+    if (!filename) return '';
+    // Match plugin._sanitize_filename: prevent path traversal, allow subdirs.
+    filename = filename.replace(/\0/g, '').replace(/\\/g, '/');
+    const parts = [];
+    for (let part of filename.split('/')) {
+        part = part.trim();
+        // Drop empty parts and segments consisting only of dots (., .., ..., etc.)
+        if (!part || /^\.+$/.test(part)) continue;
+        // Strip Windows drive letters (e.g. C:)
+        if (/^[a-zA-Z]:$/.test(part)) continue;
+        parts.push(part);
+    }
+    return parts.join('/');
+}
+
+function titleCase(str) {
+    // Python str.title(): capitalize each word, lowercase the rest.
+    return str.replace(/\w\S*/g, t => t.charAt(0).toUpperCase() + t.slice(1).toLowerCase());
+}
+
+function buildButtonContainer(bundleId, elements) {
+    const cfg = window.zipBundleConfig || {};
+    const labelSuffix = cfg.labelSuffix || '(.zip)';
+
+    const btn = document.createElement('button');
+    btn.className = 'md-button zip-bundle-btn';
+    btn.setAttribute('data-bundle-id', bundleId);
+    btn.type = 'button';
+    btn.setAttribute('aria-label', `Download ${bundleId.replace(/-/g, ' ')} bundle`);
+
+    const customLabel = elements
+        .map(el => el.getAttribute('data-zip-label'))
+        .find(Boolean);
+    const forceZip = elements.some(el => el.getAttribute('data-zip-force') === 'true');
+
+    if (customLabel) {
+        btn.textContent = customLabel;
+    } else if (elements.length === 1 && !forceZip) {
+        const rawFilename = elements[0].getAttribute('data-zip-filename');
+        const filename = sanitizeFilename(rawFilename || '') || 'file';
+        const displayName = filename.split('/').pop() || 'file';  // basename
+        btn.textContent = `Download ${displayName}`;
+    } else {
+        const label = titleCase(bundleId.replace(/-/g, ' '));
+        btn.textContent = `Download ${label} ${labelSuffix}`.trim();
+    }
+
+    const container = document.createElement('div');
+    container.className = 'zip-bundle-container';
+    container.appendChild(btn);
+    return container;
+}
+
+function injectZipButtons() {
+    const tagged = document.querySelectorAll('[data-zip-bundle]');
+    if (tagged.length === 0) return;
+
+    // Group elements by bundle id, preserving document order.
+    const bundles = new Map();
+    tagged.forEach(el => {
+        if (el.hasAttribute('data-zip-filename')) {
+            el.setAttribute('data-zip-filename',
+                sanitizeFilename(el.getAttribute('data-zip-filename')));
+        }
+        const id = el.getAttribute('data-zip-bundle');
+        if (!bundles.has(id)) bundles.set(id, []);
+        bundles.get(id).push(el);
+    });
+
+    bundles.forEach((elements, id) => {
+        // Idempotent: skip if a button already exists (server-injected or a
+        // prior run under instant navigation).
+        const sel = `.zip-bundle-btn[data-bundle-id="${CSS.escape(id)}"]`;
+        if (document.querySelector(sel)) return;
+        const container = buildButtonContainer(id, elements);
+        elements[elements.length - 1].insertAdjacentElement('afterend', container);
+    });
+}
+
+// Run on initial load and on every (instant) navigation. Material/Zensical
+// expose the document$ observable; fall back to DOMContentLoaded elsewhere.
+if (window.document$ && typeof window.document$.subscribe === 'function') {
+    window.document$.subscribe(injectZipButtons);
+} else if (document.readyState !== 'loading') {
+    injectZipButtons();
+} else {
+    document.addEventListener('DOMContentLoaded', injectZipButtons);
+}
+
+// ── Download handling ─────────────────────────────────────────────────
+
+function extractCodeContent(el) {
+    const codeEl = el.querySelector('code') || el;
+    const clone = codeEl.cloneNode(true);
+    // Strip line numbers, Material code annotations, and clipboard buttons
+    clone.querySelectorAll('.linenos, .lineno, .md-annotation, .md-clipboard').forEach(n => n.remove());
+    return clone.textContent;
+}
+
+document.addEventListener('click', function(e) {
+    const btn = e.target.closest('.zip-bundle-btn[data-bundle-id]');
+    if (btn) {
+        downloadZipBundle(btn.getAttribute('data-bundle-id'));
+    }
+});
+
+async function downloadZipBundle(bundleId) {
+    const escapedId = (window.CSS && CSS.escape) ? CSS.escape(bundleId) : bundleId.replace(/"/g, '\\"');
+    const elements = document.querySelectorAll(`[data-zip-bundle="${escapedId}"]`);
+
+    if (elements.length === 0) {
+        console.warn(`No elements found for bundle ID: ${bundleId}`);
+        return;
+    }
+
+    const forceZip = Array.from(elements).some(el => el.getAttribute('data-zip-force') === 'true');
+
+    // If it's only one file AND we aren't forcing a ZIP, download it directly
+    if (elements.length === 1 && !forceZip) {
+        const el = elements[0];
+        const rawFilename = el.getAttribute('data-zip-filename');
+        const filename = sanitizeFilename(rawFilename || '') || 'file';
+        const content = extractCodeContent(el);
+
+        // Ensure UTF-8 encoding
+        const blob = new Blob([content], { type: "text/plain;charset=utf-8" });
+        const url = URL.createObjectURL(blob);
+        triggerDownload(url, filename);
+        return;
+    }
+
+    // Multiple files (or forced single ZIP)
+    if (typeof JSZip === 'undefined') {
+        console.error('JSZip is not loaded. Please include it in your mkdocs.yml extra_javascript or enable it in the plugin config.');
+        alert('Error: ZIP library not loaded.');
+        return;
+    }
+
+    const zip = new JSZip();
+    elements.forEach(el => {
+        const rawFilename = el.getAttribute('data-zip-filename');
+        const filename = sanitizeFilename(rawFilename || '') || 'unnamed-file';
+        const content = extractCodeContent(el);
+
+        zip.file(filename, content, { date: new Date(0) });
+    });
+
+    const blob = await zip.generateAsync({
+        type: "blob",
+        compression: "DEFLATE",
+        compressionOptions: { level: 6 }
+    });
+    const url = URL.createObjectURL(blob);
+    triggerDownload(url, `${bundleId}.zip`);
+}
+
+function triggerDownload(url, filename) {
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    document.body.removeChild(a);
+    URL.revokeObjectURL(url);
+}

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/mkdocs_zip_bundle/plugin.py

@@ -43,15 +43,22 @@ class ZipBundlePlugin(BasePlugin):
         """
         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()
+        if not filename:
+            return ""
+        # Remove null bytes and normalize slashes
+        filename = filename.replace('\0', '').replace('\\', '/')
+        # Split into path components and clean each segment
+        parts = []
+        for part in filename.split('/'):
+            part = part.strip()
+            # Drop empty segments and any segment consisting only of dots (., .., ...)
+            if not part or re.fullmatch(r'\.+', part):
+                continue
+            # Strip Windows drive letters if leading (e.g. 'C:')
+            if len(part) == 2 and part[1] == ':' and part[0].isalpha():
+                continue
+            parts.append(part)
+        return '/'.join(parts)
 
     def _create_button(self, soup, bundle_id, elements):
         """
@@ -70,9 +77,9 @@ class ZipBundlePlugin(BasePlugin):
         if custom_label:
             btn.string = custom_label
         elif len(elements) == 1 and not force_zip:
-            filename = elements[0].get('data-zip-filename', 'file')
+            filename = elements[0].get('data-zip-filename') or 'file'
             # Extract only the base filename for the button label if it's a path
-            display_name = os.path.basename(filename)
+            display_name = os.path.basename(filename) or 'file'
             btn.string = f"Download {display_name}"
         else:
             label = bundle_id.replace('-', ' ').title()

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/mkdocs_zip_bundle_plugin.egg-info/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: mkdocs-zip-bundle-plugin
-Version: 0.1.1
-Summary: A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file.
+Version: 0.3.0
+Summary: Bundle code blocks into downloadable ZIP or raw files — for MkDocs/Material and Zensical.
 Author: Daemonless
-License: MIT
+License-Expression: 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
+Keywords: mkdocs,material,zensical,zip,bundle,placeholders,interactive
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -17,9 +17,11 @@ 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).
+Turn code blocks into downloadable files — for **MkDocs/Material** and **[Zensical](https://zensical.org)**. Tag any code block with a bundle ID and filename and a download button is injected 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.
+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. _(MkDocs/Material — see [Using with Zensical](https://mkdocs-zip-bundle-plugin.daemonless.io/configuration/#using-with-zensical) for the Zensical caveat.)_
+
+**[Live demo → mkdocs-zip-bundle-plugin.daemonless.io](https://mkdocs-zip-bundle-plugin.daemonless.io)**
 
 ## Features
 

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mkdocs-zip-bundle-plugin"
-version = "0.1.1"
-description = "A MkDocs plugin to bundle specific code blocks into a downloadable ZIP or raw file."
+version = "0.3.0"
+description = "Bundle code blocks into downloadable ZIP or raw files — for MkDocs/Material and Zensical."
 readme = "README.md"
 authors = [{ name = "Daemonless" }]
-license = { text = "MIT" }
+license = "MIT"
 requires-python = ">=3.8"
-keywords = ["mkdocs", "zip", "bundle", "placeholders", "interactive"]
+keywords = ["mkdocs", "material", "zensical", "zip", "bundle", "placeholders", "interactive"]
 dependencies = [
     "mkdocs>=1.4.0",
     "beautifulsoup4>=4.11.0"
@@ -24,5 +24,8 @@ Repository = "https://github.com/daemonless/mkdocs-zip-bundle-plugin"
 [project.entry-points."mkdocs.plugins"]
 zip-bundle = "mkdocs_zip_bundle.plugin:ZipBundlePlugin"
 
+[tool.setuptools.packages.find]
+include = ["mkdocs_zip_bundle*"]
+
 [tool.setuptools.package-data]
 mkdocs_zip_bundle = ["assets/*"]

{mkdocs_zip_bundle_plugin-0.1.1 → mkdocs_zip_bundle_plugin-0.3.0}/tests/test_plugin.py

@@ -34,7 +34,20 @@ def test_sanitize_filename(plugin):
     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/'
+    assert plugin._sanitize_filename('//double//slash//') == 'double/slash'
+    # Traversal bypass attempts
+    assert plugin._sanitize_filename('....//test.txt') == 'test.txt'
+    assert plugin._sanitize_filename('....//....//etc/passwd') == 'etc/passwd'
+    assert plugin._sanitize_filename('a/b/../../../c') == 'a/b/c'
+    assert plugin._sanitize_filename('C:\\Windows\\System32\\cmd.exe') == 'Windows/System32/cmd.exe'
+    assert plugin._sanitize_filename('foo/./bar') == 'foo/bar'
+    assert plugin._sanitize_filename('\0secret.txt') == 'secret.txt'
+    # Empty and dot-only inputs
+    assert plugin._sanitize_filename('   ') == ''
+    assert plugin._sanitize_filename('') == ''
+    assert plugin._sanitize_filename('..') == ''
+    assert plugin._sanitize_filename('...') == ''
+    assert plugin._sanitize_filename(None) == ''
 
 
 # --- _create_button ---
@@ -50,6 +63,16 @@ def test_create_button_single(plugin):
     assert 'onclick' not in button.attrs
 
 
+def test_create_button_single_empty_filename(plugin):
+    """Empty or traversal-only filename should fall back safely to 'Download file'."""
+    soup = BeautifulSoup('', 'html.parser')
+    elements = [make_element(soup, {'data-zip-filename': ''})]
+    container = plugin._create_button(soup, 'my-bundle', elements)
+
+    button = container.find('button')
+    assert button.string == 'Download file'
+
+
 def test_create_button_single_subdir(plugin):
     soup = BeautifulSoup('', 'html.parser')
     elements = [make_element(soup, {'data-zip-filename': 'configs/compose.yaml'})]

mkdocs_zip_bundle_plugin-0.1.1/mkdocs_zip_bundle/assets/zip-bundle.js

@@ -1,67 +0,0 @@
-document.addEventListener('click', function(e) {
-    const btn = e.target.closest('.zip-bundle-btn[data-bundle-id]');
-    if (btn) {
-        downloadZipBundle(btn.getAttribute('data-bundle-id'));
-    }
-});
-
-async function downloadZipBundle(bundleId) {
-    const elements = document.querySelectorAll(`[data-zip-bundle="${bundleId}"]`);
-    
-    if (elements.length === 0) {
-        console.warn(`No elements found for bundle ID: ${bundleId}`);
-        return;
-    }
-
-    const forceZip = Array.from(elements).some(el => el.getAttribute('data-zip-force') === 'true');
-
-    // If it's only one file AND we aren't forcing a ZIP, download it directly
-    if (elements.length === 1 && !forceZip) {
-        const el = elements[0];
-        const filename = el.getAttribute('data-zip-filename') || 'file';
-        const codeEl = el.querySelector('code') || el;
-        const content = codeEl.innerText;
-        
-        // Ensure UTF-8 encoding
-        const blob = new Blob([content], { type: "text/plain;charset=utf-8" });
-        const url = URL.createObjectURL(blob);
-        triggerDownload(url, filename);
-        return;
-    }
-
-    // Multiple files (or forced single ZIP)
-    if (typeof JSZip === 'undefined') {
-        console.error('JSZip is not loaded. Please include it in your mkdocs.yml extra_javascript or enable it in the plugin config.');
-        alert('Error: ZIP library not loaded.');
-        return;
-    }
-
-    const zip = new JSZip();
-    elements.forEach(el => {
-        const filename = el.getAttribute('data-zip-filename') || 'unnamed-file';
-        const codeEl = el.querySelector('code') || el;
-        const content = codeEl.innerText;
-        
-        // Skip empty files if they have no content
-        if (content.trim().length === 0) {
-            console.warn(`Skipping empty file: ${filename}`);
-            return;
-        }
-
-        zip.file(filename, content);
-    });
-
-    const blob = await zip.generateAsync({type: "blob"});
-    const url = URL.createObjectURL(blob);
-    triggerDownload(url, `${bundleId}.zip`);
-}
-
-function triggerDownload(url, filename) {
-    const a = document.createElement('a');
-    a.href = url;
-    a.download = filename;
-    document.body.appendChild(a);
-    a.click();
-    document.body.removeChild(a);
-    URL.revokeObjectURL(url);
-}