hexo-plugin-waterfall 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 wuhunyu
+
+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.

package/README.md

@@ -0,0 +1,86 @@
+# hexo-plugin-waterfall
+
+Hexo 瀑布流图片画廊插件，支持 Lightbox 放大预览和图片懒加载。
+
+## 安装
+
+```bash
+npm install hexo-plugin-waterfall --save
+```
+
+或者将插件目录复制到 Hexo 项目的 `node_modules` 目录下。
+
+## 配置
+
+在 Hexo 的 `_config.yml` 中添加以下配置：
+
+```yaml
+waterfall:
+  enable: true        # 是否启用插件
+  columns: 3          # 默认列数
+  gap: 10px           # 图片间距
+  borderRadius: 5px   # 图片圆角
+  lazyload: true      # 启用懒加载
+  lightbox: true      # 启用点击放大
+```
+
+## 使用
+
+在 Markdown 文件中使用 `waterfall` 标签：
+
+```markdown
+{% waterfall 3 %}
+<img alt="图片描述1" src="/images/photo1.jpg"/>
+<img alt="图片描述2" src="/images/photo2.jpg"/>
+<img alt="图片描述3" src="/images/photo3.jpg"/>
+<img alt="图片描述4" src="/images/photo4.jpg"/>
+{% endwaterfall %}
+```
+
+### 参数说明
+
+- `3`：可选参数，指定列数。如果不指定，则使用配置文件中的 `columns` 值。
+
+### 图片属性
+
+- `src`：图片路径（必填）
+- `alt`：图片描述（可选），在 Lightbox 中会显示为图片标题
+
+## 功能特性
+
+### 瀑布流布局
+
+使用 CSS `column-count` 实现瀑布流布局，自动响应式适配：
+- 桌面端：使用指定列数
+- 平板端（<=768px）：2 列
+- 手机端（<=480px）：1 列
+
+### Lightbox 放大预览
+
+- 点击图片弹出全屏预览
+- 左右箭头切换图片
+- 键盘支持：← → 切换，ESC 关闭
+- 显示图片描述（alt 属性）
+- 显示图片计数器
+
+### 图片懒加载
+
+- 使用 IntersectionObserver API
+- 图片进入可视区域时才加载
+- 加载前显示占位动画
+- 加载完成淡入效果
+
+## 示例效果
+
+```markdown
+{% waterfall 4 %}
+<img alt="春日樱花" src="/gallery/sakura.jpg"/>
+<img alt="夏日海滩" src="/gallery/beach.jpg"/>
+<img alt="秋日红叶" src="/gallery/autumn.jpg"/>
+<img alt="冬日雪景" src="/gallery/winter.jpg"/>
+{% endwaterfall %}
+```
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,19 @@
+'use strict';
+
+const loadConfig = require('./lib/config');
+const registerTag = require('./lib/tag');
+const registerFilter = require('./lib/filter');
+
+// Load configuration
+const config = loadConfig(hexo);
+
+// Skip if disabled
+if (!config.enable) {
+    return;
+}
+
+// Register tag: {% waterfall n %} ... {% endwaterfall %}
+hexo.extend.tag.register('waterfall', registerTag(hexo, config), { ends: true });
+
+// Register filter: inject CSS and JS after HTML render
+hexo.extend.filter.register('after_render:html', registerFilter(hexo, config));

package/lib/config.js

@@ -0,0 +1,15 @@
+'use strict';
+
+module.exports = function (hexo) {
+    const defaultConfig = {
+        enable: true,
+        columns: 3,
+        gap: '10px',
+        borderRadius: '5px',
+        lazyload: true,
+        lightbox: true
+    };
+
+    const config = hexo.config.waterfall || {};
+    return Object.assign({}, defaultConfig, config);
+};

package/lib/consts.js

@@ -0,0 +1,6 @@
+'use strict';
+
+module.exports = {
+    WATERFALL_CONTAINER: 'waterfall-container',
+    WATERFALL_ITEM: 'waterfall-item'
+};

package/lib/filter.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const { WATERFALL_CONTAINER } = require('./consts');
+const templates = require('./templates');
+
+/**
+ * Register filter to inject CSS and JS
+ * @param {object} hexo - Hexo instance
+ * @param {object} config - Plugin configuration
+ * @returns {function} Filter handler function
+ */
+module.exports = function (hexo, config) {
+    return function (str) {
+        // Only inject if page contains waterfall container
+        if (str.indexOf(WATERFALL_CONTAINER) === -1) {
+            return str;
+        }
+
+        const assets = templates.renderInjectedAssets(config);
+
+        // Inject before </body>
+        return str.replace('</body>', assets + '</body>');
+    };
+};

package/lib/tag.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const templates = require('./templates');
+
+/**
+ * Extract attribute value from img tag
+ * @param {string} imgTag - The full img tag string
+ * @param {string} attrName - Attribute name to extract
+ * @returns {string} Attribute value or empty string
+ */
+function extractAttribute(imgTag, attrName) {
+    // Match both single and double quotes
+    const regex = new RegExp(attrName + '=["\']([^"\']*)["\']', 'i');
+    const match = imgTag.match(regex);
+    return match ? match[1] : '';
+}
+
+/**
+ * Parse img tags from content
+ * @param {string} content - HTML content containing img tags
+ * @returns {Array} Array of image objects {src, alt}
+ */
+function parseImages(content) {
+    const images = [];
+    // Match all <img> tags
+    const imgTagRegex = /<img\s+[^>]*\/?>/gi;
+    let match;
+
+    while ((match = imgTagRegex.exec(content)) !== null) {
+        const imgTag = match[0];
+        const src = extractAttribute(imgTag, 'src');
+
+        // Only add if src exists
+        if (src) {
+            images.push({
+                src: src,
+                alt: extractAttribute(imgTag, 'alt')
+            });
+        }
+    }
+
+    return images;
+}
+
+/**
+ * Register waterfall tag handler
+ * @param {object} hexo - Hexo instance
+ * @param {object} config - Plugin configuration
+ * @returns {function} Tag handler function
+ */
+module.exports = function (hexo, config) {
+    return function (args, content) {
+        // Parse columns from args, fallback to config default
+        // Validate range: 1-12
+        let columns = parseInt(args[0], 10) || config.columns;
+        columns = Math.min(Math.max(columns, 1), 12);
+
+        // Parse images from content
+        const images = parseImages(content);
+
+        if (images.length === 0) {
+            return '';
+        }
+
+        // Generate HTML
+        return templates.renderTagHtml(images, columns, config);
+    };
+};

package/lib/templates.js

@@ -0,0 +1,462 @@
+'use strict';
+
+const { WATERFALL_CONTAINER, WATERFALL_ITEM } = require('./consts');
+
+/**
+ * Escape HTML special characters to prevent XSS
+ * @param {string} str - Input string
+ * @returns {string} Escaped string
+ */
+function escapeHtml(str) {
+    if (!str) return '';
+    return String(str)
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/'/g, ''')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/**
+ * Sanitize CSS value to prevent CSS injection
+ * @param {string} value - CSS value
+ * @param {string} defaultValue - Default fallback value
+ * @returns {string} Sanitized value
+ */
+function sanitizeCssValue(value, defaultValue) {
+    if (!value) return defaultValue;
+    // Only allow valid CSS length values
+    if (/^[\d.]+(px|em|rem|%|vw|vh)?$/.test(String(value))) {
+        return value;
+    }
+    return defaultValue;
+}
+
+/**
+ * Generate HTML for the waterfall tag
+ * @param {Array} images - Array of image objects {src, alt}
+ * @param {number} columns - Number of columns
+ * @param {object} config - Plugin configuration
+ * @returns {string} HTML string
+ */
+exports.renderTagHtml = function (images, columns, config) {
+    const imagesHtml = images.map((img, index) => {
+        const safeSrc = escapeHtml(img.src);
+        const safeAlt = escapeHtml(img.alt || '');
+        const src = config.lazyload ? '' : safeSrc;
+        const dataSrc = config.lazyload ? `data-src="${safeSrc}"` : '';
+        const lazyClass = config.lazyload ? 'waterfall-lazy' : '';
+        const clickHandler = config.lightbox ? `onclick="event.stopPropagation(); event.preventDefault(); waterfallLightbox.open(this, ${index})"` : '';
+
+        return `
+            <div class="${WATERFALL_ITEM}">
+                <img src="${src}" ${dataSrc} alt="${safeAlt}" class="${lazyClass}" ${clickHandler}/>
+            </div>
+        `;
+    }).join('');
+
+    return `
+        <div class="${WATERFALL_CONTAINER}" style="--wf-columns: ${columns};" data-columns="${columns}">
+            ${imagesHtml}
+        </div>
+    `;
+};
+
+/**
+ * Generate CSS and JS to inject into the page
+ * @param {object} config - Plugin configuration
+ * @returns {string} CSS and JS string
+ */
+exports.renderInjectedAssets = function (config) {
+    // Sanitize CSS values
+    const safeGap = sanitizeCssValue(config.gap, '10px');
+    const safeBorderRadius = sanitizeCssValue(config.borderRadius, '5px');
+    const safeColumns = Math.min(Math.max(parseInt(config.columns, 10) || 3, 1), 12);
+
+    const css = `
+<style>
+/* Waterfall Container */
+.${WATERFALL_CONTAINER} {
+    column-count: var(--wf-columns, ${safeColumns});
+    column-gap: ${safeGap};
+    width: 100%;
+}
+
+/* Waterfall Item */
+.${WATERFALL_ITEM} {
+    break-inside: avoid;
+    margin-bottom: ${safeGap};
+}
+
+.${WATERFALL_ITEM} img {
+    width: 100%;
+    display: block;
+    border-radius: ${safeBorderRadius};
+    transition: transform 0.3s ease, opacity 0.3s ease;
+    cursor: ${config.lightbox ? 'pointer' : 'default'};
+}
+
+.${WATERFALL_ITEM} img:hover {
+    transform: scale(1.02);
+}
+
+/* Lazy Loading Styles */
+.waterfall-lazy {
+    background: linear-gradient(90deg, #f0f0f0 25%, #e0e0e0 50%, #f0f0f0 75%);
+    background-size: 200% 100%;
+    animation: waterfall-shimmer 1.5s infinite;
+    min-height: 150px;
+    opacity: 0;
+}
+
+.waterfall-lazy.loaded {
+    background: none;
+    animation: none;
+    opacity: 1;
+    min-height: auto;
+}
+
+.waterfall-lazy.error {
+    background: #f5f5f5;
+    animation: none;
+    opacity: 1;
+    min-height: 100px;
+}
+
+@keyframes waterfall-shimmer {
+    0% { background-position: 200% 0; }
+    100% { background-position: -200% 0; }
+}
+
+/* Lightbox Styles */
+.waterfall-lightbox-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    background: rgba(0, 0, 0, 0.9);
+    z-index: 9999;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    opacity: 0;
+    pointer-events: none;
+    transition: opacity 0.3s ease;
+}
+
+.waterfall-lightbox-overlay.active {
+    opacity: 1;
+    pointer-events: auto;
+}
+
+.waterfall-lightbox-content {
+    position: relative;
+    max-width: 90vw;
+    max-height: 80vh;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+}
+
+.waterfall-lightbox-content img {
+    max-width: 100%;
+    max-height: 75vh;
+    object-fit: contain;
+    border-radius: 4px;
+}
+
+.waterfall-lightbox-caption {
+    color: #fff;
+    text-align: center;
+    padding: 15px 20px;
+    font-size: 14px;
+    max-width: 80vw;
+}
+
+.waterfall-lightbox-close {
+    position: absolute;
+    top: 20px;
+    right: 20px;
+    color: #fff;
+    font-size: 30px;
+    cursor: pointer;
+    z-index: 10001;
+    width: 40px;
+    height: 40px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: transform 0.2s ease;
+}
+
+.waterfall-lightbox-close:hover {
+    transform: scale(1.1);
+}
+
+.waterfall-lightbox-nav {
+    position: absolute;
+    top: 50%;
+    transform: translateY(-50%);
+    color: #fff;
+    font-size: 40px;
+    cursor: pointer;
+    padding: 20px;
+    user-select: none;
+    transition: opacity 0.2s ease;
+    z-index: 10001;
+}
+
+.waterfall-lightbox-nav:hover {
+    opacity: 0.7;
+}
+
+.waterfall-lightbox-prev {
+    left: 20px;
+}
+
+.waterfall-lightbox-next {
+    right: 20px;
+}
+
+.waterfall-lightbox-counter {
+    position: absolute;
+    bottom: 20px;
+    left: 50%;
+    transform: translateX(-50%);
+    color: rgba(255, 255, 255, 0.7);
+    font-size: 14px;
+}
+
+/* Responsive Breakpoints */
+@media (max-width: 768px) {
+    .${WATERFALL_CONTAINER} {
+        column-count: 2 !important;
+    }
+
+    .waterfall-lightbox-nav {
+        font-size: 30px;
+        padding: 10px;
+    }
+
+    .waterfall-lightbox-prev {
+        left: 10px;
+    }
+
+    .waterfall-lightbox-next {
+        right: 10px;
+    }
+}
+
+@media (max-width: 480px) {
+    .${WATERFALL_CONTAINER} {
+        column-count: 1 !important;
+    }
+}
+</style>`;
+
+    let script = '';
+
+    // Lazy loading script
+    if (config.lazyload) {
+        script += `
+<script>
+(function() {
+    var lazyImages = document.querySelectorAll('.waterfall-lazy');
+
+    if ('IntersectionObserver' in window) {
+        var observer = new IntersectionObserver(function(entries) {
+            entries.forEach(function(entry) {
+                if (entry.isIntersecting) {
+                    var img = entry.target;
+                    var src = img.getAttribute('data-src');
+                    if (src) {
+                        img.src = src;
+                        img.onload = function() {
+                            img.classList.add('loaded');
+                        };
+                        img.onerror = function() {
+                            img.classList.add('loaded');
+                            img.classList.add('error');
+                        };
+                        img.removeAttribute('data-src');
+                    }
+                    observer.unobserve(img);
+                }
+            });
+        }, { rootMargin: '50px' });
+
+        lazyImages.forEach(function(img) {
+            observer.observe(img);
+        });
+    } else {
+        // Fallback for browsers without IntersectionObserver
+        lazyImages.forEach(function(img) {
+            var src = img.getAttribute('data-src');
+            if (src) {
+                img.src = src;
+                img.onload = function() {
+                    img.classList.add('loaded');
+                };
+                img.onerror = function() {
+                    img.classList.add('loaded');
+                    img.classList.add('error');
+                };
+            }
+        });
+    }
+})();
+</script>`;
+    }
+
+    // Lightbox script
+    if (config.lightbox) {
+        script += `
+<script>
+var waterfallLightbox = (function() {
+    var overlay = null;
+    var images = [];
+    var currentIndex = 0;
+
+    function createOverlay() {
+        if (overlay) return;
+
+        overlay = document.createElement('div');
+        overlay.className = 'waterfall-lightbox-overlay';
+        overlay.innerHTML =
+            '<span class="waterfall-lightbox-close">&times;</span>' +
+            '<span class="waterfall-lightbox-nav waterfall-lightbox-prev">&#10094;</span>' +
+            '<span class="waterfall-lightbox-nav waterfall-lightbox-next">&#10095;</span>' +
+            '<div class="waterfall-lightbox-content">' +
+                '<img src="" alt=""/>' +
+                '<div class="waterfall-lightbox-caption"></div>' +
+            '</div>' +
+            '<div class="waterfall-lightbox-counter"></div>';
+
+        document.body.appendChild(overlay);
+
+        // Close button
+        overlay.querySelector('.waterfall-lightbox-close').addEventListener('click', function(e) {
+            e.stopPropagation();
+            e.preventDefault();
+            close();
+        });
+
+        // Nav buttons
+        overlay.querySelector('.waterfall-lightbox-prev').addEventListener('click', function(e) {
+            e.stopPropagation();
+            prev();
+        });
+        overlay.querySelector('.waterfall-lightbox-next').addEventListener('click', function(e) {
+            e.stopPropagation();
+            next();
+        });
+
+        // Close on overlay click
+        overlay.addEventListener('click', function(e) {
+            if (e.target === overlay) {
+                close();
+            }
+        });
+
+        // Keyboard navigation
+        document.addEventListener('keydown', handleKeydown);
+    }
+
+    function handleKeydown(e) {
+        if (!overlay || !overlay.classList.contains('active')) return;
+
+        switch(e.key) {
+            case 'Escape':
+                close();
+                break;
+            case 'ArrowLeft':
+                prev();
+                break;
+            case 'ArrowRight':
+                next();
+                break;
+        }
+    }
+
+    function collectImages(clickedImg) {
+        var container = clickedImg.closest('.${WATERFALL_CONTAINER}');
+        var imgs = container.querySelectorAll('.${WATERFALL_ITEM} img');
+        images = Array.prototype.map.call(imgs, function(img) {
+            return {
+                src: img.getAttribute('data-src') || img.src,
+                alt: img.alt || ''
+            };
+        });
+    }
+
+    function showImage(index) {
+        if (index < 0 || index >= images.length) return;
+
+        currentIndex = index;
+        var img = overlay.querySelector('.waterfall-lightbox-content img');
+        var caption = overlay.querySelector('.waterfall-lightbox-caption');
+        var counter = overlay.querySelector('.waterfall-lightbox-counter');
+
+        img.src = images[index].src;
+        img.alt = images[index].alt;
+        caption.textContent = images[index].alt;
+        caption.style.display = images[index].alt ? 'block' : 'none';
+        counter.textContent = (index + 1) + ' / ' + images.length;
+
+        // Show/hide nav buttons
+        overlay.querySelector('.waterfall-lightbox-prev').style.display = images.length > 1 ? 'block' : 'none';
+        overlay.querySelector('.waterfall-lightbox-next').style.display = images.length > 1 ? 'block' : 'none';
+    }
+
+    function open(clickedImg, index) {
+        createOverlay();
+        collectImages(clickedImg);
+        showImage(index);
+
+        // Prevent body scroll
+        document.body.style.overflow = 'hidden';
+
+        // Show overlay with animation
+        requestAnimationFrame(function() {
+            overlay.classList.add('active');
+        });
+    }
+
+    function close() {
+        if (!overlay) return;
+
+        overlay.classList.remove('active');
+        document.body.style.overflow = '';
+
+        setTimeout(function() {
+            images = [];
+            currentIndex = 0;
+        }, 300);
+    }
+
+    function prev() {
+        var newIndex = currentIndex - 1;
+        if (newIndex < 0) newIndex = images.length - 1;
+        showImage(newIndex);
+    }
+
+    function next() {
+        var newIndex = currentIndex + 1;
+        if (newIndex >= images.length) newIndex = 0;
+        showImage(newIndex);
+    }
+
+    return {
+        open: open,
+        close: close,
+        prev: prev,
+        next: next
+    };
+})();
+</script>`;
+    }
+
+    return css + script;
+};

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "hexo-plugin-waterfall",
+  "version": "0.1.0",
+  "main": "index.js",
+  "keywords": [
+    "hexo",
+    "plugin",
+    "waterfall",
+    "gallery",
+    "lightbox"
+  ],
+  "author": "wuhunyu",
+  "license": "MIT",
+  "description": "Hexo waterfall image gallery plugin with lightbox support."
+}