Snap2HTML-py（Snap2HTML 的 Python & Web 版 / Python & Web Edition）

原 Snap2HTML（C#/WinForms）的跨平台重制版：把硬盘上的目录结构"拍一个快照"，生成单个可搜索的 HTML 清单文件——树形导航、内置搜索、纯文本 / CSV / JSON 导出，全部封装在一个便于保存与分发的 HTML 文件里。

生成结果与原版数据格式（V2）完全兼容，界面沿用原版查看器模板（已本地化为中文），在原版基础上扩展了多目录合并与跨设备 Web 工作台。

原版项目主页 / Original upstream homepage: http://www.rlvision.com/snap2html

在线演示 / Live demo: https://snap2html-demo.vercel.app（Web 工作台静态演示：点"生成快照"体验模拟扫描流程，完成后的清单即本工具真实生成）

A cross-platform re-implementation of Snap2HTML (C#/WinForms): snapshot a directory tree into a single searchable HTML listing — tree navigation, built-in search, plain text / CSV / JSON export, all wrapped in one easily stored and shared HTML file.

The output is fully compatible with the upstream data format (V2) and reuses the original viewer template (localized to Chinese), extended with multi-directory merging and a cross-device web workbench.

Live demo: https://snap2html-demo.vercel.app (static demo of the web workbench — click "Generate Snapshot" for a simulated scan; the resulting listing is really generated by this tool)

组成 / Components

• snap2html.py — 核心工具，仅依赖 Python 3.8+ 标准库：CLI 扫描生成 + --serve Web 工作台，可在 Windows / Debian / Ubuntu / macOS 直接运行。

• template.html — 清单查看器模板（工作台同风格的零依赖瘦身版），作为单文件本体嵌入每个生成结果。引擎为原生 JS（无 jQuery / dynatree 等依赖，模板体积从 ~310KB 降至 ~49KB），支持树形导航、搜索（*/? 通配符与 f:/d:/> 前缀）、列排序、纯文本 / CSV / JSON 导出、深浅主题、中英切换与多根目录。

• template-default.html — 备选模板：沿用原版 Snap2HTML 外观的零依赖版（深 / 浅双主题、中文界面）。

• RedeMeDev.txt — 数据格式 V1 / V2 说明，以及浏览器控制台读取清单数据的 JS 接口文档。

• snap2html.py — the core tool, Python 3.8+ standard library only: CLI generation plus the --serve web workbench; runs on Windows / Debian / Ubuntu / macOS.

• template.html — the listing viewer template (workbench-styled, rewritten with zero dependencies), embedded into every generated file. The engine is plain vanilla JS (no jQuery / dynatree and the like; template size cut from ~310KB to ~49KB) with tree navigation, search (*/? wildcards and f:/d:/> prefixes), column sorting, plain text / CSV / JSON export, dark / light themes, zh / en UI and multi-root listings.

• template-default.html — an optional alternative template keeping the upstream Snap2HTML look & feel (zero dependencies, dark / light themes, Chinese UI).

• RedeMeDev.txt — data format V1 / V2 specs and the browser-console API for reading listing data.

下载即用 / Download & run

不想安装 Python？从 Releases 下载对应平台的打包版，无需任何 Python 环境：

• Windows：Snap2HTML-py.exe —— 双击即启动 Web 工作台（自动打开浏览器）；关闭窗口即停止服务。命令行用法与源码版完全一致。

• Linux x86_64：Snap2HTML-py-linux-x86_64.tar.gz —— 解压后直接运行 ./Snap2HTML-py，无需安装 Python：

  tar -xzf Snap2HTML-py-linux-x86_64.tar.gz
  chmod +x Snap2HTML-py
  ./Snap2HTML-py

  无参数运行自动进入 Web 工作台；CLI 参数与 Python 源码版保持一致。

• Linux ARM64：Snap2HTML-py-linux-aarch64.tar.gz —— Oracle Cloud ARM / AWS Graviton / 树莓派等 ARM64 Linux 使用（x86_64 包无法在 ARM64 机器上运行）；解压运行方式同上，把文件名换成 aarch64 即可。

• macOS：Snap2HTML-py-macos.zip —— 解压后在终端运行 ./Snap2HTML-py（首次运行需 chmod +x Snap2HTML-py）。

无需安装 Python 的打包版由 GitHub Actions 在每次发版时自动构建。

Don't want to install Python? Grab the packaged build for your platform from the Releases page — no Python environment needed:

• Windows: Snap2HTML-py.exe — double-click to start the web workbench (opens your browser automatically); closing the window stops the service. The command-line usage is identical to the source version.

• Linux x86_64: Snap2HTML-py-linux-x86_64.tar.gz — extract and run ./Snap2HTML-py directly, no Python needed:

  tar -xzf Snap2HTML-py-linux-x86_64.tar.gz
  chmod +x Snap2HTML-py
  ./Snap2HTML-py

  Running with no arguments starts the web workbench automatically; CLI arguments are identical to the Python source version.

• Linux ARM64: Snap2HTML-py-linux-aarch64.tar.gz — for Oracle Cloud ARM / AWS Graviton / Raspberry Pi and other ARM64 Linux machines (the x86_64 package cannot run on ARM64); extract and run the same way, just swap the filename for aarch64.

• macOS: Snap2HTML-py-macos.zip — unzip and run ./Snap2HTML-py in a terminal (run chmod +x Snap2HTML-py the first time).

The dependency-free builds are produced automatically by GitHub Actions on every release.

CLI 用法 / CLI usage

# 单目录 / single directory
python snap2html.py /home/user/docs -o docs.html

# 多目录一次生成（合并为一份多根清单）/ multiple directories in one listing
python snap2html.py /data/projects /data/archive -o all.html

# 合并已生成的清单文件 / merge previously generated listings
python snap2html.py --merge a.html b.html c.html -o merged.html

# 常用选项 / common options:
#   --template 指定查看器模板 / use a custom viewer template (default: template.html in this directory)
#   python snap2html.py 目录 -o out.html --template template-default.html
#   --hidden   包含隐藏项 / include hidden items (dot files; Windows Hidden attr; macOS UF_HIDDEN)
#   --system   包含系统项 / include system items (Windows System attr)
#   --follow   跟随目录符号链接 / follow directory symlinks
#   --link     生成文件链接 / generate file links (auto file:// URI if no value)
#   --title    页面标题 / page title

Web 工作台 / Web workbench

--serve 启动一个零依赖的本地 Web 服务，专为无桌面的 Ubuntu / Debian 服务器设计：在服务器上运行，用任意设备的浏览器操作。目录可点选（内置服务端目录浏览器，Windows 下列盘符、POSIX 下从根开始）也可手填；支持多目录合并生成、实时进度、深色 / 浅色主题切换、结果在线查看与下载；还能把本机已有的清单上传到服务器参与合并。

安全提示 / Security note: Web 服务无鉴权，默认仅监听 127.0.0.1；用 --host 0.0.0.0 开放到局域网后，同网段用户可扫描这台机器的任意目录。请只在可信网络使用，或用 SSH 隧道 / 带认证的反向代理保护。

--serve starts a dependency-free local web service designed for headless Ubuntu / Debian boxes: run it on the server, drive it from any device's browser. Directories can be picked with the built-in server-side browser (drive letters on Windows, / on POSIX) or typed by hand; multiple directories merge into one listing; progress is live; dark / light themes are switchable; results can be viewed and downloaded in the browser; listings from other machines can be uploaded and merged too.

The web service has no authentication and binds to 127.0.0.1 by default. Exposing it via --host 0.0.0.0 lets anyone on that network scan arbitrary directories on the machine — use it on trusted networks only, or front it with an SSH tunnel / an authenticating reverse proxy.

python snap2html.py --serve --host 0.0.0.0 --port 8765
# 浏览器访问 / open in browser: http://<server-ip>:8765/

多目录与合并的原理 / How multi-root & merging work

数据格式 V2 原生支持多根目录：每个根目录的数据块 ID 独立从 0 开始，模板自动在顶部渲染一个虚拟根节点并汇总统计。因此"多目录扫描"与"清单合并"都只是把各来源的数据块按顺序拼接进同一份模板（受 nilaoda/Snap2HTMLMerger 启发）。

The V2 data format natively supports multiple roots: each root's data block numbers its IDs from 0 independently, and the template automatically renders a virtual root on top with combined statistics. Both multi-directory scanning and merging therefore simply concatenate the sources' data blocks into one template (inspired by nilaoda/Snap2HTMLMerger).

与原版的关系 / Relationship to upstream

本项目是 Snap2HTML 的独立重实现：纯 Python + Web，不包含原版 C# 代码；保留数据格式文档与查看器模板，以维持生成结果与原版完全兼容。

查看器模板与数据格式基于上游 Snap2HTML v2.52（commit 66fbcf4，2026-01-05）；上游发布新版本后可对照更新。

This project is an independent re-implementation of Snap2HTML in pure Python + Web and contains none of the original C# code; the data-format docs and viewer template are kept so output stays fully compatible with upstream.

The viewer template and data format are based on upstream Snap2HTML v2.52 (commit 66fbcf4, 2026-01-05); newer upstream releases can be compared and merged in.

生成的 HTML 应用示例 / The finished HTML app

本项目的在线演示：snap2html-demo.vercel.app —— 首页是 Web 工作台的静态演示版（UI 与真实 --serve 页面一致，扫描流程为模拟），点“生成快照”→“查看结果”进入的清单页由 snap2html.py 以默认模板真实扫描示例目录（18 个文件夹 / 77 个文件）生成。仓库内对应 demo/index.html（工作台演示版）与 demo/listing/index.html（生成产物）。

Web 工作台 / Web workbench	生成的清单查看器（默认模板）/ Generated listing viewer (default template)

Live demo of this project: snap2html-demo.vercel.app — the landing page is a static demo of the web workbench (same UI as the real --serve page, with a simulated scan); the listing behind “Generate Snapshot” → “View result” was really generated by snap2html.py from a sample directory (18 folders / 77 files) using the default template. See demo/index.html (workbench demo) and demo/listing/index.html (generated output) in this repo.

Credits 致谢

• 原版 Snap2HTML / Original Snap2HTML: rlv-dan/Snap2HTML（RLVision，GPL-3.0）
• 合并功能思路参考 / Merge feature inspired by: nilaoda/Snap2HTMLMerger（GPL-3.0）
• 本项目沿用 GPL-3.0 许可证 / This project is GPL-3.0 licensed，见 / see LICENSE。