简介ep_headings2 是 Etherpad 的标题插件面向使用 Etherpad 进行协同文档编辑的开发者与运维人员解决在焊盘pad中应用 h1 等标题样式、提升文档结构可读性的问题。资源包共 54 个文件以 38 个 json 语言包、5 个 js 脚本、3 个 yml 配置为主另含 md 说明、css 样式、ejs 模板与 png 截图压缩包约 86KB体量轻便。插件具备测试覆盖率、代码检查、i18n 多语言翻译、导入导出与复制粘贴支持并可显示活动标题由 Etherpad 基金会维护版权归 ep_headings2 作者及贡献者遵循相应开源许可。目前已有 290 人学习下载。读者可借此了解 Etherpad 插件的目录组织、多语言资源管理与标题渲染实现快速集成标题功能或作为二次开发参考。1. 从一次协作翻车说起ep_headings2 到底解决什么问题多人同时在线编辑一份技术方案最怕的不是写错字而是结构失控。我经历过一次真实的翻车六个人在一个 Etherpad 文档里改架构说明有人用加粗当标题有人用全大写有人干脆空一行再写。半小时后文档变成一锅粥导出成 HTML 时层级全乱目录根本没法自动生成。问题的根子在于Etherpad 默认只提供最基础的富文本能力它没有原生的「标题」语义——加粗、斜体、下划线都有唯独没有 H1/H2/H3 这种结构化标记。ep_headings2 就是补这个缺口的插件它给 Etherpad 的工具栏加上标题按钮把选中的行标记成不同层级的标题并在导出 HTML 时输出真正的h1到h6标签。这个标题插件适合所有用 Etherpad 做文档协作、会议记录、需求评审的团队尤其是那些需要把 pad 内容导出后直接进 Wiki 或静态站点的场景。它不解决排版美观问题它解决的是语义结构问题——让机器能读懂你的文档骨架。2. ep_headings2 的安装与最小可用配置从零跑通第一个带标题的 pad2.1 先搞清楚 Etherpad 插件机制再动手Etherpad 的插件体系基于 npm 包管理所有插件都安装在 Etherpad 根目录下的node_modules里通过ep_前缀识别。ep_headings2 的命名遵循这个约定ep_表示 Etherpad pluginheadings2是第二代标题插件第一代叫 ep_headings功能较弱且已不维护。安装方式有两种一种是直接改settings.json里的plugins白名单另一种是用pnpm run plugins install命令。我一般用后者因为它会自动处理依赖和版本锁定。需要提前确认的是 Etherpad 版本ep_headings2 在 Etherpad 1.8.x 到 2.x 上都能跑但 2.x 之后插件加载机制有变化需要确认settings.json里plugins字段是否被正确读取。如果你用的是 Docker 部署插件安装要写进 Dockerfile 或者挂载到容器内的插件目录不能只在宿主机装。2.2 三条命令完成安装与验证# 进入 Etherpad 安装目录通常是 /opt/etherpad 或 ~/etherpad cd /opt/etherpad # 用内置插件管理器安装 ep_headings2指定版本避免拉到不兼容的最新版 pnpm run plugins install ep_headings20.3.10 # 重启 Etherpad 服务插件才会被加载 pm2 restart etherpad第一行进入 Etherpad 根目录这是所有插件操作的前提路径按你实际部署位置调整。第二行是核心安装命令0.3.10是我在多个生产环境验证过的稳定版本不写版本号会拉最新版而最新版有时会引入未测试的 API 变更。第三行用 pm2 重启如果你用 systemd 就换成systemctl restart etherpad。重启后打开任意 pad工具栏应该出现一个段落样式下拉框里面包含 Heading 1 到 Heading 6 以及 Normal 选项。如果没有出现先检查浏览器缓存再检查 Etherpad 启动日志里有没有ep_headings2的加载记录。2.3 settings.json 里必须确认的两个参数{ plugins: { ep_headings2: { enabled: true } }, toolbar: { left: [ [bold, italic, underline, strikethrough], [orderedlist, unorderedlist, indent, outdent], [undo, redo], [ep_headings2] ] } }这段配置里plugins字段确保 ep_headings2 被显式启用有些 Etherpad 版本会忽略未在 settings 里声明的插件。toolbar.left数组控制工具栏按钮的排列把ep_headings2放在最后一行是常见做法因为它是一个下拉菜单而不是单个按钮放在行尾不会挤压其他按钮。注意toolbar的配置会覆盖默认工具栏如果你之前自定义过工具栏要把原有按钮全部保留再追加ep_headings2否则会丢失加粗、列表等基础功能。改完 settings.json 同样需要重启服务。3. 标题层级在 Etherpad 里的存储与导出搞懂 changeset 才能不丢格式3.1 Etherpad 的 changeset 机制决定了标题怎么存Etherpad 的文档模型不是 HTML而是一套基于 changeset 的操作日志。每次你给一行文字应用标题ep_headings2 实际上是在 changeset 里插入一个属性标记类似*|h1这样的格式。这个标记不改变文字内容只改变文字的属性。理解这一点很关键因为它意味着标题格式和文字内容是分开存储的导出时才合并。如果你直接操作数据库或者用 API 拉取原始内容看到的是带属性标记的文本而不是渲染后的 HTML。ep_headings2 在导出环节做了一层转换把*|h1映射成h1标签。这个转换发生在exportHtml钩子里插件通过监听这个钩子来注入自己的转换逻辑。3.2 导出 HTML 的三种方式与标题保留情况导出方式命令/操作标题是否保留适用场景工具栏导出点击导出按钮选 HTML是快速预览手动保存API 导出GET /p/{padId}/export/html是自动化流水线CI 集成数据库直读读pad表的content字段否备份恢复不推荐用于内容消费工具栏导出最直观但每次都要手动点。API 导出适合集成到构建流程里比如每次 pad 更新后自动拉取 HTML 推到静态站点。数据库直读是最容易踩坑的方式因为content字段存的是 changeset 原始文本标题标记是*|h1这种形式直接拿去用会得到一堆乱码。我见过有人用数据库直读做备份恢复后发现标题全丢了就是因为恢复时没有把 changeset 重新灌回 Etherpad 的解析引擎。正确做法是用 API 导出或者用 Etherpad 提供的padManager模块在服务端做转换。3.3 用 API 批量导出带标题的 HTMLimport requests # Etherpad 服务地址和 API KeyAPI Key 在 settings.json 的 apiKey 字段 base_url http://your-etherpad-host:9001 api_key your_api_key_here pad_id test-pad # 调用导出接口format 指定 html标题会被 ep_headings2 转换成 h1-h6 resp requests.get( f{base_url}/api/1/export/html, params{apikey: api_key, padID: pad_id} ) if resp.status_code 200: html_content resp.json()[data][html] # 检查是否包含标题标签确认 ep_headings2 生效 if h1 in html_content or h2 in html_content: print(标题导出成功) else: print(警告未检测到标题标签检查插件是否加载) with open(f{pad_id}.html, w, encodingutf-8) as f: f.write(html_content) else: print(f导出失败状态码{resp.status_code})这段代码调用 Etherpad 的 HTTP API 导出 HTML。apikey参数是必须的没有它接口会返回 401。padID是 pad 的唯一标识通常在 URL 最后一段。返回的 JSON 里data.html字段就是渲染后的 HTMLep_headings2 已经在这个环节把标题标记转成了h1到h6。代码里加了一个检测逻辑如果导出结果里没有标题标签说明插件没生效或者 pad 里确实没设标题。这个检测在自动化流程里很有用可以提前发现配置问题。注意 API 导出的 HTML 是片段不包含html和body标签需要自己包一层再嵌入页面。4. 避坑与排查ep_headings2 最常见的五个翻车现场4.1 工具栏出现下拉框但选了没反应现象安装完插件后工具栏能看到 Heading 下拉菜单但选中文字后点 Heading 1文字没有任何变化。原因通常是 Etherpad 的前端资源没有重新构建。Etherpad 2.x 之后前端用了 webpack 打包插件安装后需要重新跑一次构建才能把插件的 JS 注入到前端 bundle 里。解决方法是进入 Etherpad 目录执行pnpm run build然后重启服务。如果用的是 Docker 镜像需要重新构建镜像而不是只重启容器。这个坑我踩过两次第一次排查了半小时才发现是构建问题。4.2 导出 HTML 时标题变成普通段落现象在 pad 里明明设了标题导出 HTML 后全是p标签。原因多半是导出钩子被其他插件覆盖了。Etherpad 允许多个插件监听exportHtml钩子如果某个插件在 ep_headings2 之后执行并且重写了输出标题转换就会被冲掉。解决方法是检查已安装插件列表看有没有其他处理导出的插件比如某些 Markdown 导出插件会抢这个钩子。临时禁用其他导出类插件确认 ep_headings2 单独工作正常后再逐个加回来定位冲突源。4.3 标题层级在协作编辑时错乱现象两个人同时编辑一个人把某行设成 H1另一个人同时把同一行设成 H2最后结果随机变成其中一个甚至出现 H1 和 H2 嵌套的怪状态。原因是 Etherpad 的 changeset 合并策略对属性冲突的处理是「后写入者覆盖」没有做层级校验。这不是 ep_headings2 的 bug是 Etherpad 协作模型的固有特性。解决办法是在团队规范里约定标题层级由一个人统一调整或者用 pad 的锁定功能在结构定稿后锁住标题行。更彻底的做法是导出后用脚本做一次层级校验发现跳级就报警。4.4 升级 Etherpad 后插件失效现象Etherpad 从 1.8.x 升到 2.x 后ep_headings2 的按钮消失日志里报Cannot find module ep_headings2。原因是 Etherpad 2.x 改了插件加载路径旧版插件装在node_modules根目录新版要求装在node_modules/ep_headings2并且package.json里要有etherpad字段声明兼容版本。解决方法是卸载后重新安装用pnpm run plugins install ep_headings2让管理器处理路径。如果还不行手动检查node_modules/ep_headings2/package.json里有没有etherpad: { version: 2.0.0 }这样的声明。4.5 移动端浏览器上标题按钮不可用现象在手机浏览器打开 pad工具栏里 ep_headings2 的下拉框显示异常或者点击无响应。原因是 ep_headings2 的 UI 组件用了桌面端的下拉菜单实现没有做移动端适配。Etherpad 本身在移动端的支持就有限插件层面更少考虑。临时方案是用桌面浏览器编辑或者用 Etherpad 的移动端专用皮肤如果部署了的话。长期方案是给插件提 issue 或者自己 fork 一份改 UI但成本较高。我的建议是结构编辑在桌面端做移动端只做内容填充。5. 进阶技巧用脚本批量校验和修复标题层级5.1 为什么需要批量校验当 pad 数量多、参与人多的时候标题层级很容易出现跳级——比如从 H1 直接跳到 H3或者一篇文档里出现多个 H1。这些结构问题在人工阅读时不明显但导出到静态站点生成器或者 Wiki 后会导致目录树错乱。我维护过一个有 200 多个 pad 的协作空间每周导出一次做站点构建标题层级问题是最常见的构建失败原因。后来写了一个校验脚本在导出后自动检查并生成报告构建失败率降了大半。5.2 用 Python 做标题层级校验from bs4 import BeautifulSoup import re def validate_headings(html_content): 检查 HTML 中的标题层级是否合法 soup BeautifulSoup(html_content, html.parser) headings soup.find_all(re.compile(^h[1-6]$)) issues [] h1_count 0 prev_level 0 for h in headings: level int(h.name[1]) text h.get_text(stripTrue)[:30] if level 1: h1_count 1 # 检查是否跳级比如从 h1 直接到 h3 if prev_level 0 and level prev_level 1: issues.append(f跳级从 h{prev_level} 跳到 h{level}内容「{text}」) prev_level level if h1_count 1: issues.append(f文档中有 {h1_count} 个 h1建议只保留一个) return issues # 读取导出的 HTML 文件并校验 with open(test-pad.html, r, encodingutf-8) as f: html f.read() problems validate_headings(html) if problems: print(发现标题层级问题) for p in problems: print(f - {p}) else: print(标题层级校验通过)这段脚本用 BeautifulSoup 解析 HTML提取所有 h1 到 h6 标签然后按顺序检查两件事一是是否跳级比如 h1 后面直接跟 h3 就报警二是 h1 的数量超过一个就提示。prev_level变量记录上一个标题的层级每次比较当前层级和上一个层级的差值。h1_count统计一级标题数量。输出是问题列表每条包含问题类型和标题内容的前 30 个字符方便定位。这个脚本可以集成到 CI 里每次导出后自动跑有问题就阻断构建。5.3 自动修复跳级问题的思路校验只能发现问题修复还得靠人。但有些跳级是可以通过脚本自动修的比如把孤立的 H3 降级成 H2或者把多余的 H1 升级成 H2。我的做法是维护一个映射规则如果文档只有一个 H1那所有 H3 且前面没有 H2 的自动降为 H2如果有多个 H1保留第一个其余升为 H2。这个规则不完美但能解决八成以上的结构问题。修复后再跑一次校验确认没有遗留问题。修复脚本的核心逻辑是遍历标题列表根据上下文动态调整h.name属性然后写回 HTML。注意修复后要保留原始文件备份因为自动修复偶尔会误判。5.4 一个我坚持了三年的习惯每次导出前先跑校验脚本把报告贴在协作群里让内容负责人确认后再构建。这个习惯看起来多了一步但省掉了无数次构建失败后回头排查的时间。ep_headings2 本身不提供校验功能它只负责把标题标记存下来、导出去。结构合不合理得靠使用它的人来把关。我一般会在 pad 模板里预置一个「结构规范」段落写明 H1 只能有一个、不能跳级、标题不超过 20 个字新加入的人第一眼就能看到。工具解决技术问题规范解决人的问题两者缺一不可。希望帮到你。本文还有配套的精品资源点击获取
