尧图网站建设 
简介这是一款面向 Etherpad 二次开发者的标题插件用于在协作编辑器中为文本块应用 h1 等标题样式解决纯文本焊盘缺乏层级结构的问题。插件由 Etherpad 基金会维护具备测试覆盖率、代码检查、国际化翻译、导入导出与复制粘贴支持并可在编辑栏显示当前活动标题适合需要扩展编辑器排版能力的前端开发者参考。资源包共 54 个文件约 86KB以 38 个 json 语言包和 5 个 js 核心脚本为主另含 yml 持续集成配置、md 说明文档、css 样式、ejs 模板及 png 截图目录涵盖 static、tests、locales 与 .github 工作流等模块。目前已有 290 人学习下载。通过阅读源码与多语言词条读者可掌握 Etherpad 插件的注册机制、钩子调用与国际化组织方式并借鉴其测试与发布流程为自行开发同类插件提供可复用的工程范例。1. ep_headings2Etherpad 标题插件到底解决什么问题多人协同编辑里最容易被忽视、但一崩就全员抓狂的是标题层级。Etherpad 原生只给你加粗、斜体、下划线这套行内样式想表达「这是一级标题、那是三级标题」只能靠手动放大字号加粗——结果就是每个人审美不同文档结构一塌糊涂。ep_headings2 就是冲着这个痛点来的它给 Etherpad 的工具栏塞进一个标题下拉框让你像在 Word 里一样选 Heading 1 到 Heading 6底层用h1~h6标签落库导出 HTML 时结构完整保留。这个插件适合谁自建 Etherpad 做内部知识库、会议纪要、需求文档的团队尤其是那些受够了「标题全靠手调字号」的运维和前端。它不解决排版美观只解决结构语义——但恰恰是结构语义决定了你的文档能不能被搜索、被导出、被程序二次处理。2. ep_headings2 的安装与最小可跑通配置2.1 先搞清楚 Etherpad 插件机制再动手Etherpad 从 1.x 开始把插件体系独立成ep_前缀的 npm 包插件通过settings.json里的plugins白名单加载运行时由ep_plugin_manager统一调度。ep_headings2 本质上做了三件事往工具栏注册一个select控件、往ace编辑器注册一套heading命令、往导出管线注册 HTML 转换规则。理解这三层后面排错才不会瞎猜。安装前确认你的 Etherpad 版本。老版本1.8 以前用的是ep_headings新版才叫ep_headings2两者 API 不兼容装错直接白屏。我一般先跑npm ls etherpad看核心版本再决定装哪个。2.2 安装命令与 settings.json 配置进入 Etherpad 根目录用 npm 装插件然后改配置。注意 Etherpad 的插件必须装在主程序同级目录不能全局装。# 进入 Etherpad 安装目录 cd /opt/etherpad # 安装 ep_headings2指定版本避免拉到不兼容的最新版 npm install ep_headings20.2.10 --no-save # 确认装上了 ls node_modules | grep ep_headings2装完后编辑settings.json把插件加进白名单并开启工具栏按钮{ plugins: { ep_headings2: { disabled: false } }, toolbar: { left: [ [bold, italic, underline, strikethrough], [heading1, heading2, heading3, heading4, heading5, heading6], [orderedlist, unorderedlist, indent, outdent] ] } }plugins段里disabled: false是显式启用Etherpad 默认不加载未声明的插件。toolbar.left数组决定按钮顺序heading1~heading6是 ep_headings2 注册的命令名写错一个字母按钮就不显示。改完重启 Etherpad 进程刷新页面就能在工具栏看到标题下拉。2.3 验证插件是否真正生效别只看按钮出现就以为成了。打开浏览器控制台输入pad.plugins.ep_headings2看对象是否存在再新建一个 pad选中一行文字点 Heading 1然后查看 pad 的 HTML 导出地址栏加/export/html确认输出里是h1而不是span stylefont-size:...。这一步能筛掉 80% 的「按钮在但功能废」的情况。提示如果按钮出现但点击无反应九成是toolbar配置里命令名和插件注册名对不上回node_modules/ep_headings2/static/js/里翻源码确认。3. 标题层级在 Etherpad 里的存储与导出逻辑3.1 标题在 pad 数据里长什么样Etherpad 的文档模型是「行 属性」的扁平结构每行文本带一组 attribute。ep_headings2 给行加的 attribute 是heading值就是h1~h6。你看到的视觉层级是前端 ace 编辑器根据这个 attribute 渲染的不是存了 HTML 标签。这意味着两件事第一标题是行级属性不能只给半行文字加标题第二导出时靠转换器把 attribute 翻译成标签。理解这点很关键。很多人想「给标题加个自定义 class」直接改 CSS 是没用的因为渲染路径是 attribute → ace 渲染器 → DOM你得改插件的导出钩子。3.2 导出 HTML 与 Markdown 的差异ep_headings2 默认只处理 HTML 导出。导出 HTML 时h1~h6会正确输出但导出 Markdown 时如果没装配套的 markdown 导出插件标题会退化成普通段落。我踩过这个坑团队用 Markdown 归档结果所有标题全平了。解决办法是确认导出链路。Etherpad 的导出是插件链式的ep_headings2注册了exportHtml钩子但exportMarkdown需要额外插件如ep_markdown配合。检查settings.json里export相关配置或者直接在导出 URL 里试/export/markdown看输出。// 在浏览器控制台快速检查当前 pad 的标题属性 const lines pad.getInternalRevisionAText ? null : null; // 更直接的办法调 ace 的 API 遍历行 const editor pad.ace; editor.getDocument().getAllLines().forEach((line, i) { const attrs editor.getLineAttributes(i); if (attrs.heading) { console.log(第 ${i} 行是 ${attrs.heading}: ${line}); } });这段代码遍历 pad 每一行打印带heading属性的行。getLineAttributes(i)返回该行的属性对象heading字段就是 ep_headings2 写入的值。跑一遍你就能确认标题到底存没存进去比看界面靠谱。3.3 标题层级对搜索和目录的影响Etherpad 自带全文搜索但默认不区分标题层级。ep_headings2 存了heading属性后如果你想让搜索按标题加权得自己写查询逻辑——Etherpad 的搜索 API 返回的是行号你可以根据行属性做二次排序。另一个常见需求是自动生成目录TOC这需要遍历所有行、提取heading属性、按h1~h6嵌套输出。插件本身不提供 TOC但数据模型支持你写一个。4. 避坑ep_headings2 部署中最容易翻车的 5 个点4.1 现象工具栏按钮出现但点击后文字没变化原因toolbar配置里的命令名和插件实际注册名不一致。ep_headings2 注册的是heading1到heading6但有些教程写成h1或heading_1Etherpad 找不到命令就静默失败。解决打开node_modules/ep_headings2/static/js/index.js搜toolbar.registerCommand或registerAceCommand确认命令名。然后逐字对照settings.json里的写法。4.2 现象升级 Etherpad 后插件报错pad 打不开原因Etherpad 大版本升级会改插件 API。ep_headings2 依赖ep_plugin_manager的钩子签名1.8 到 1.9 之间aceGetDefaultEditor的返回值结构变过老插件直接崩。解决先看 Etherpad 的CHANGELOG确认插件 API 变更点再去 npm 上找 ep_headings2 对应版本。如果作者没更新只能自己 fork 改钩子。我一般会在升级前用 Docker 起一个测试实例把插件跑一遍再动生产。4.3 现象导出 HTML 时标题变成p标签原因导出钩子没注册成功。ep_headings2 的导出逻辑挂在exportHtml钩子上如果settings.json里plugins段写错或者插件加载顺序被其他导出插件覆盖钩子就不生效。解决在settings.json里把 ep_headings2 放在导出类插件前面确保它的钩子先注册。然后访问/export/html看源码搜h1确认。4.4 现象多人同时编辑时标题层级错乱原因Etherpad 的 OTOperational Transformation算法对行属性变更的合并有边界情况。两个人同时给同一行设不同标题级别合并结果可能取其中一个另一个人的操作被覆盖。解决这是 Etherpad 核心的已知限制插件层解决不了。规避方法是团队约定「标题只由一人定稿」或者用评论功能先讨论再改。别指望插件能处理并发冲突。4.5 现象移动端工具栏不显示标题按钮原因Etherpad 移动端用的是精简工具栏配置toolbar.left在移动端可能被toolbar.mobile覆盖。ep_headings2 只注册了桌面端命令移动端没适配。解决检查settings.json里有没有toolbar.mobile段如果有把heading1~heading6也加进去。但移动端屏幕窄六个标题按钮会挤爆建议只放heading1~heading3。5. 进阶用 ep_headings2 的数据做自动化文档处理标题属性存进行里之后能玩的花样比你想的多。我拿它做过两件事自动生成会议纪要目录、把 pad 内容按标题拆成多个页面。核心思路都是遍历行、读heading属性、按层级重组。下面这段脚本跑在 Node 环境通过 Etherpad 的 HTTP API 拉取 pad 内容然后按标题拆结构const axios require(axios); // Etherpad API 地址和 API Key 从 settings.json 里拿 const ETHERPAD_API http://localhost:9001/api/1.2.13; const API_KEY 你的APIKey; const PAD_ID test-pad; async function fetchPadText() { const url ${ETHERPAD_API}/getText?apikey${API_KEY}padID${PAD_ID}; const res await axios.get(url); return res.data.data.text; } // 注意getText 返回纯文本不带属性 // 要拿标题属性得用 getHTML 或直接读 pad 的 revision async function fetchPadHTML() { const url ${ETHERPAD_API}/getHTML?apikey${API_KEY}padID${PAD_ID}; const res await axios.get(url); return res.data.data.html; } // 从 HTML 里提取标题结构 function extractHeadings(html) { const regex /h([1-6])[^]*(.*?)\/h\1/g; const headings []; let match; while ((match regex.exec(html)) ! null) { headings.push({ level: parseInt(match[1]), text: match[2] }); } return headings; } (async () { const html await fetchPadHTML(); const headings extractHeadings(html); headings.forEach(h { console.log(${ .repeat(h.level - 1)}${h.text}); }); })();这段代码的逻辑分三步先用getHTML接口拿到 pad 的 HTML 导出这里标题已经是h1~h6标签然后用正则匹配所有标题标签最后按层级缩进打印成目录树。getHTML返回的 HTML 里标题标签是 ep_headings2 导出钩子生成的所以前提是插件导出功能正常。正则里的\1是反向引用确保开闭标签层级一致避免匹配到嵌套错误。参数说明ETHERPAD_API的版本号1.2.13要和你 Etherpad 实际版本对应版本号写错 API 路径会 404。API_KEY在settings.json的apiKey字段里别硬编码在脚本里用环境变量传。PAD_ID就是 pad 的 URL 最后一段。拿到标题结构后你可以做更多按h1拆分成独立文档、给每个标题生成锚点链接、统计各级标题数量做文档质量检查。我现在的习惯是每次迭代完文档跑一遍这个脚本看标题层级有没有跳级比如h1直接到h3跳级往往意味着内容结构有问题。注意Etherpad 的getHTML接口返回的是当前最新 revision 的 HTML如果 pad 正在被编辑可能拿到中间状态。生产环境建议先调getRevisionsCount确认 revision 稳定再拉取。最后说个血泪教训别在生产 pad 上直接测插件。我当初图省事在团队正在用的知识库实例上装 ep_headings2结果配置写错导致整个实例白屏全员停工半小时。后来我固定用 Docker 起一个隔离实例docker run -d -p 9002:9001 etherpad/etherpad在 9002 上折腾完再同步配置到生产。这个习惯帮我省了至少三次事故。希望帮到你。本文还有配套的精品资源点击获取 Etherpad标题插件ep_headings2：安装配置、导出逻辑与避坑指南
简介这是一款面向 Etherpad 二次开发者的标题插件用于在协作编辑器中为文本块应用 h1 等标题样式解决纯文本焊盘缺乏层级结构的问题。插件由 Etherpad 基金会维护具备测试覆盖率、代码检查、国际化翻译、导入导出与复制粘贴支持并可在编辑栏显示当前活动标题适合需要扩展编辑器排版能力的前端开发者参考。资源包共 54 个文件约 86KB以 38 个 json 语言包和 5 个 js 核心脚本为主另含 yml 持续集成配置、md 说明文档、css 样式、ejs 模板及 png 截图目录涵盖 static、tests、locales 与 .github 工作流等模块。目前已有 290 人学习下载。通过阅读源码与多语言词条读者可掌握 Etherpad 插件的注册机制、钩子调用与国际化组织方式并借鉴其测试与发布流程为自行开发同类插件提供可复用的工程范例。1. ep_headings2Etherpad 标题插件到底解决什么问题多人协同编辑里最容易被忽视、但一崩就全员抓狂的是标题层级。Etherpad 原生只给你加粗、斜体、下划线这套行内样式想表达「这是一级标题、那是三级标题」只能靠手动放大字号加粗——结果就是每个人审美不同文档结构一塌糊涂。ep_headings2 就是冲着这个痛点来的它给 Etherpad 的工具栏塞进一个标题下拉框让你像在 Word 里一样选 Heading 1 到 Heading 6底层用h1~h6标签落库导出 HTML 时结构完整保留。这个插件适合谁自建 Etherpad 做内部知识库、会议纪要、需求文档的团队尤其是那些受够了「标题全靠手调字号」的运维和前端。它不解决排版美观只解决结构语义——但恰恰是结构语义决定了你的文档能不能被搜索、被导出、被程序二次处理。2. ep_headings2 的安装与最小可跑通配置2.1 先搞清楚 Etherpad 插件机制再动手Etherpad 从 1.x 开始把插件体系独立成ep_前缀的 npm 包插件通过settings.json里的plugins白名单加载运行时由ep_plugin_manager统一调度。ep_headings2 本质上做了三件事往工具栏注册一个select控件、往ace编辑器注册一套heading命令、往导出管线注册 HTML 转换规则。理解这三层后面排错才不会瞎猜。安装前确认你的 Etherpad 版本。老版本1.8 以前用的是ep_headings新版才叫ep_headings2两者 API 不兼容装错直接白屏。我一般先跑npm ls etherpad看核心版本再决定装哪个。2.2 安装命令与 settings.json 配置进入 Etherpad 根目录用 npm 装插件然后改配置。注意 Etherpad 的插件必须装在主程序同级目录不能全局装。# 进入 Etherpad 安装目录 cd /opt/etherpad # 安装 ep_headings2指定版本避免拉到不兼容的最新版 npm install ep_headings20.2.10 --no-save # 确认装上了 ls node_modules | grep ep_headings2装完后编辑settings.json把插件加进白名单并开启工具栏按钮{ plugins: { ep_headings2: { disabled: false } }, toolbar: { left: [ [bold, italic, underline, strikethrough], [heading1, heading2, heading3, heading4, heading5, heading6], [orderedlist, unorderedlist, indent, outdent] ] } }plugins段里disabled: false是显式启用Etherpad 默认不加载未声明的插件。toolbar.left数组决定按钮顺序heading1~heading6是 ep_headings2 注册的命令名写错一个字母按钮就不显示。改完重启 Etherpad 进程刷新页面就能在工具栏看到标题下拉。2.3 验证插件是否真正生效别只看按钮出现就以为成了。打开浏览器控制台输入pad.plugins.ep_headings2看对象是否存在再新建一个 pad选中一行文字点 Heading 1然后查看 pad 的 HTML 导出地址栏加/export/html确认输出里是h1而不是span stylefont-size:...。这一步能筛掉 80% 的「按钮在但功能废」的情况。提示如果按钮出现但点击无反应九成是toolbar配置里命令名和插件注册名对不上回node_modules/ep_headings2/static/js/里翻源码确认。3. 标题层级在 Etherpad 里的存储与导出逻辑3.1 标题在 pad 数据里长什么样Etherpad 的文档模型是「行 属性」的扁平结构每行文本带一组 attribute。ep_headings2 给行加的 attribute 是heading值就是h1~h6。你看到的视觉层级是前端 ace 编辑器根据这个 attribute 渲染的不是存了 HTML 标签。这意味着两件事第一标题是行级属性不能只给半行文字加标题第二导出时靠转换器把 attribute 翻译成标签。理解这点很关键。很多人想「给标题加个自定义 class」直接改 CSS 是没用的因为渲染路径是 attribute → ace 渲染器 → DOM你得改插件的导出钩子。3.2 导出 HTML 与 Markdown 的差异ep_headings2 默认只处理 HTML 导出。导出 HTML 时h1~h6会正确输出但导出 Markdown 时如果没装配套的 markdown 导出插件标题会退化成普通段落。我踩过这个坑团队用 Markdown 归档结果所有标题全平了。解决办法是确认导出链路。Etherpad 的导出是插件链式的ep_headings2注册了exportHtml钩子但exportMarkdown需要额外插件如ep_markdown配合。检查settings.json里export相关配置或者直接在导出 URL 里试/export/markdown看输出。// 在浏览器控制台快速检查当前 pad 的标题属性 const lines pad.getInternalRevisionAText ? null : null; // 更直接的办法调 ace 的 API 遍历行 const editor pad.ace; editor.getDocument().getAllLines().forEach((line, i) { const attrs editor.getLineAttributes(i); if (attrs.heading) { console.log(第 ${i} 行是 ${attrs.heading}: ${line}); } });这段代码遍历 pad 每一行打印带heading属性的行。getLineAttributes(i)返回该行的属性对象heading字段就是 ep_headings2 写入的值。跑一遍你就能确认标题到底存没存进去比看界面靠谱。3.3 标题层级对搜索和目录的影响Etherpad 自带全文搜索但默认不区分标题层级。ep_headings2 存了heading属性后如果你想让搜索按标题加权得自己写查询逻辑——Etherpad 的搜索 API 返回的是行号你可以根据行属性做二次排序。另一个常见需求是自动生成目录TOC这需要遍历所有行、提取heading属性、按h1~h6嵌套输出。插件本身不提供 TOC但数据模型支持你写一个。4. 避坑ep_headings2 部署中最容易翻车的 5 个点4.1 现象工具栏按钮出现但点击后文字没变化原因toolbar配置里的命令名和插件实际注册名不一致。ep_headings2 注册的是heading1到heading6但有些教程写成h1或heading_1Etherpad 找不到命令就静默失败。解决打开node_modules/ep_headings2/static/js/index.js搜toolbar.registerCommand或registerAceCommand确认命令名。然后逐字对照settings.json里的写法。4.2 现象升级 Etherpad 后插件报错pad 打不开原因Etherpad 大版本升级会改插件 API。ep_headings2 依赖ep_plugin_manager的钩子签名1.8 到 1.9 之间aceGetDefaultEditor的返回值结构变过老插件直接崩。解决先看 Etherpad 的CHANGELOG确认插件 API 变更点再去 npm 上找 ep_headings2 对应版本。如果作者没更新只能自己 fork 改钩子。我一般会在升级前用 Docker 起一个测试实例把插件跑一遍再动生产。4.3 现象导出 HTML 时标题变成p标签原因导出钩子没注册成功。ep_headings2 的导出逻辑挂在exportHtml钩子上如果settings.json里plugins段写错或者插件加载顺序被其他导出插件覆盖钩子就不生效。解决在settings.json里把 ep_headings2 放在导出类插件前面确保它的钩子先注册。然后访问/export/html看源码搜h1确认。4.4 现象多人同时编辑时标题层级错乱原因Etherpad 的 OTOperational Transformation算法对行属性变更的合并有边界情况。两个人同时给同一行设不同标题级别合并结果可能取其中一个另一个人的操作被覆盖。解决这是 Etherpad 核心的已知限制插件层解决不了。规避方法是团队约定「标题只由一人定稿」或者用评论功能先讨论再改。别指望插件能处理并发冲突。4.5 现象移动端工具栏不显示标题按钮原因Etherpad 移动端用的是精简工具栏配置toolbar.left在移动端可能被toolbar.mobile覆盖。ep_headings2 只注册了桌面端命令移动端没适配。解决检查settings.json里有没有toolbar.mobile段如果有把heading1~heading6也加进去。但移动端屏幕窄六个标题按钮会挤爆建议只放heading1~heading3。5. 进阶用 ep_headings2 的数据做自动化文档处理标题属性存进行里之后能玩的花样比你想的多。我拿它做过两件事自动生成会议纪要目录、把 pad 内容按标题拆成多个页面。核心思路都是遍历行、读heading属性、按层级重组。下面这段脚本跑在 Node 环境通过 Etherpad 的 HTTP API 拉取 pad 内容然后按标题拆结构const axios require(axios); // Etherpad API 地址和 API Key 从 settings.json 里拿 const ETHERPAD_API http://localhost:9001/api/1.2.13; const API_KEY 你的APIKey; const PAD_ID test-pad; async function fetchPadText() { const url ${ETHERPAD_API}/getText?apikey${API_KEY}padID${PAD_ID}; const res await axios.get(url); return res.data.data.text; } // 注意getText 返回纯文本不带属性 // 要拿标题属性得用 getHTML 或直接读 pad 的 revision async function fetchPadHTML() { const url ${ETHERPAD_API}/getHTML?apikey${API_KEY}padID${PAD_ID}; const res await axios.get(url); return res.data.data.html; } // 从 HTML 里提取标题结构 function extractHeadings(html) { const regex /h([1-6])[^]*(.*?)\/h\1/g; const headings []; let match; while ((match regex.exec(html)) ! null) { headings.push({ level: parseInt(match[1]), text: match[2] }); } return headings; } (async () { const html await fetchPadHTML(); const headings extractHeadings(html); headings.forEach(h { console.log(${ .repeat(h.level - 1)}${h.text}); }); })();这段代码的逻辑分三步先用getHTML接口拿到 pad 的 HTML 导出这里标题已经是h1~h6标签然后用正则匹配所有标题标签最后按层级缩进打印成目录树。getHTML返回的 HTML 里标题标签是 ep_headings2 导出钩子生成的所以前提是插件导出功能正常。正则里的\1是反向引用确保开闭标签层级一致避免匹配到嵌套错误。参数说明ETHERPAD_API的版本号1.2.13要和你 Etherpad 实际版本对应版本号写错 API 路径会 404。API_KEY在settings.json的apiKey字段里别硬编码在脚本里用环境变量传。PAD_ID就是 pad 的 URL 最后一段。拿到标题结构后你可以做更多按h1拆分成独立文档、给每个标题生成锚点链接、统计各级标题数量做文档质量检查。我现在的习惯是每次迭代完文档跑一遍这个脚本看标题层级有没有跳级比如h1直接到h3跳级往往意味着内容结构有问题。注意Etherpad 的getHTML接口返回的是当前最新 revision 的 HTML如果 pad 正在被编辑可能拿到中间状态。生产环境建议先调getRevisionsCount确认 revision 稳定再拉取。最后说个血泪教训别在生产 pad 上直接测插件。我当初图省事在团队正在用的知识库实例上装 ep_headings2结果配置写错导致整个实例白屏全员停工半小时。后来我固定用 Docker 起一个隔离实例docker run -d -p 9002:9001 etherpad/etherpad在 9002 上折腾完再同步配置到生产。这个习惯帮我省了至少三次事故。希望帮到你。本文还有配套的精品资源点击获取