后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本指南以 HedgeDoc 仓库中backend/src/database/seeds/notes/local_user_note.md为核心剖析一条“种子笔记seed note”的完整生命周期从 Markdown YAML frontmatter 的书写格式到 Knex 种子脚本如何将其解析、落库为 note、revision、tag、author 等关联数据再到本地测试用户test/test123如何借助这些数据完成登录与 API 调试。读完你将掌握 HedgeDoc 开发环境种子数据的全貌并能自行编写、扩充属于自己的测试笔记与幻灯片。一、local_user_note.md 在 HedgeDoc 中扮演什么角色HedgeDocIdeas grow better together的仓库采用 pnpm workspace 组织为backend、frontend、commons、database等多个包。其中backend/src/database/seeds/目录存放的是仅供开发与测试环境使用的数据库种子数据用于在初始化数据库后立刻填充一批可交互的用户、笔记和 API Token方便开发者在前端与后端联调时直接使用而不必手工创建内容。backend/src/database/seeds/notes/local_user_note.md就是这批种子中的一份普通文档类型DOCUMENT测试笔记它的完整内容如下--- title: Local Test User Note 1 description: A test note for the local test user tags: - user - note --- # Title Some Text - [ ] Write A ToDo-List - [ ] Check some items这份文件同时承载了两层信息YAML frontmatter顶部---包裹区域声明笔记的标题、描述与标签元数据Markdown 正文一段包含一级标题、正文和待办清单Task List的示例内容用于验证文档渲染与待办交互。与它同目录的还有两份姊妹文件guest_note.md游客用户测试笔记和 local_user_slide.md本地测试用户的幻灯片演示文档三者共同构成种子笔记的三个典型形态。二、frontmatter 语法种子笔记的元数据规范local_user_note.md的 frontmatter 使用了三个字段title、description、tags。这三个字段并非随意约定而是对应 HedgeDoc 统一的笔记 frontmatter 解析规范其底层 Schema 定义在 commons/src/note-frontmatter/note-frontmatter.ts 中。完整可用的 frontmatter 字段包括均由 zod Schema 校验并带有默认值字段类型默认值说明titlestring笔记标题descriptionstring笔记描述tagsstring[][]标签列表用于 explore探索页面过滤typeDOCUMENT/SLIDEDOCUMENT使用的渲染器类型robotsstringrobots meta 标签内容langISO 639-1 枚举en笔记语言dirLTR/RTLLTR文字书写方向breaksbooleantrue是否将换行视为换段licensestring追加到 HTML 的版权声明头opengraphrecord{}OpenGraph meta 标签slideOptionsrecord见 default-note-frontmatter.tsReveal.js 幻灯片选项如transition: zoom、autoSlide: 0解析管线位于 commons/src/note-frontmatter/parse-note-frontmatter.ts先用js-yaml的load把 YAML 文本解析为对象再交给NoteFrontmatterSchema.safeParse做类型校验。若解析失败或字段非法则回退到默认 frontmatterdefaultNoteFrontmatter保证笔记依然可用。Schema 使用.passthrough()因此未被列出的自定义字段会被保留但忽略——这也是种子笔记只需要写三个字段就能工作的原因。三、种子脚本如何消费这份 Markdown 文件真正把local_user_note.md变成数据库记录的是 backend/src/database/seeds/03_note.ts。该脚本以seed(knex)为入口执行过程分为四个阶段1. 清空既有数据保证幂等await knex(TableNote).del(); await knex(TableAlias).del(); await knex(TableRevision).del(); await knex(TableRevisionTag).del(); await knex(TableAuthorshipInfo).del(); await knex(TableNoteGroupPermission).del(); await knex(TableNoteUserPermission).del();种子脚本可重复执行Knex seed 天然支持每次运行前先把与笔记相关的 7 张表清空避免重复数据污染。2. 读取 Markdown 文件并提取元数据const userNoteContent readFileSync(./notes/local_user_note.md, utf-8); const { title: userNoteTitle, description: userNoteDescription, tags: userNoteTags, } extractRevisionMetadataFromContent(userNoteContent);注意readFileSync的相对路径以backend/为基准种子目录下执行读取后交由extractRevisionMetadataFromContent处理。该函数的实现位于 backend/src/revisions/utils/extract-revision-metadata-from-content.ts它内部完成了用extractFrontmatter切分出 frontmatter 与正文调用parseNoteFrontmatter得到结构化的NoteFrontmatter通过generateNoteTitle生成标题——优先取 frontmatter 的title若为空则用extractFirstHeadingFromContentmarkdown-it 渲染 HTML 后提取第一个h1兜底提取description缺省为与tags缺省为[]并根据type字段得出NoteType。这正是种子笔记与运行时真实笔记走完全相同的元数据解析链路的体现种子数据不是“写死的数据库行”而是与真实创建笔记一致的解析产物。3. 写入 notes / aliases / revisions 主数据脚本按固定顺序插入三份笔记对应guest-note、user-note、user-slide三个主别名其中local_user_note.md对应userNoteAlias user-noteowner 为本地测试用户ownerId: 2版本号为 2publiclyVisible: false。随后为每份笔记创建 revision其中[FieldNameRevision.uuid]: userNoteRevisionUuid, [FieldNameRevision.patch]: createPatch(userNoteAlias, , userNoteContent), [FieldNameRevision.content]: userNoteContent, [FieldNameRevision.noteType]: NoteType.DOCUMENT, [FieldNameRevision.title]: userNoteTitle, [FieldNameRevision.description]: userNoteDescription,content直接保存整份 Markdown 原文patch通过diff包的createPatch(alias, , content)生成从空内容到全文的差异补丁这是 HedgeDoc 增量同步的基础数据结构noteType取NoteType.DOCUMENT对应 frontmatter 中未声明type字段时的默认文档类型可见 local_user_note.md 中确实没有写type正依赖默认值。4. 写入 tags、authorship 与权限关联数据脚本接着把解析出的标签user、note逐条插入TableRevisionTag关联到userNoteRevisionUuid随后在TableAuthorshipInfo中记录该 revision 的整段内容startPosition: 0到endPosition: content.length归属作者authorId: 2本地测试用户这是“谁写了哪段文字”的溯源信息最后写入组权限与用户权限TableNoteGroupPermission组 1 对 note 2 不可编辑canEdit: falseTableNoteUserPermission用户 2 对 note 2、3 可编辑canEdit: true。至此一份纯文本的 Markdown 种子笔记被完整物化为 note、alias、revision、revision-tag、authorship-info、group-permission、user-permission 七张表的关联数据。四、与之配套的本地测试用户与登录凭证local_user_note.md归属的ownerId: 2其用户信息由 backend/src/database/seeds/01_user.ts 定义用户名test显示名Local Test User作者样式authorStyle: 2登录身份AuthProviderType.LOCAL本地用户名密码方式密码哈希hashPassword(test123)的结果也就是说在开发环境运行种子后你可以直接用用户名test、密码test123登录 HedgeDoc然后通过主别名user-note访问这份种子笔记。同脚本还创建了游客用户Guest 1guestUuid固定对应guest-note笔记。此外backend/src/database/seeds/02_api_token.ts 为test用户预置了一个有效期为一年的 API Tokenlabel 为Local Test User API Tokensecret 以 SHA-512 哈希存储可用于直接调用 backend 的私有 API 做接口调试例如配合 e2e 测试套件backend/test/private-api使用。五、如何运行种子Knex 命令与开发数据库配置种子的执行由 Knex 驱动。开发环境的数据库配置在 backend/knexfile.tsdevelopment: { client: better-sqlite3, connection: { filename: ./hedgedoc.sqlite }, useNullAsDefault: true, migrations: { directory: ./src/database/migrations }, seeds: { directory: ./src/database/seeds }, }开发库默认使用better-sqlite3单文件数据库hedgedoc.sqlite种子目录指向src/database/seeds。backend 的 package.json 为此提供了便捷脚本backend/package.jsonnpm run knex -- seeds:run实际展开为tsx ../node_modules/.bin/knex --migrations-directory src/database/migrations --knexfile ./knexfile.ts seeds:run。运行前请先执行迁移npm run knex -- migrate:latest迁移脚本位于 backend/src/database/migrations/20250312211152_initial.js在应用启动时也会由 backend/src/migrate.ts 自动检查并执行。种子脚本的执行顺序依赖 Knex 对文件名的排序01_user.ts→02_api_token.ts→03_note.ts确保先有用户与 Token再创建笔记因此你可以放心地反复seeds:run——每份种子文件都会先清空对应表再插入。六、从种子笔记到真实笔记模板参考与扩展建议local_user_note.md虽然只有十几行却是一份“最小可用的 HedgeDoc 笔记”范本值得复用的要点包括frontmatter 写最小集titledescriptiontags即可其余字段type、lang、breaks、slideOptions等都有默认值按需补充正文验证交互能力- [ ]待办清单在 HedgeDoc 前端会被渲染为可勾选的 Task List相关渲染插件见 markdown-it-plugins/src/task-lists种子笔记因此也是前端 cypress 测试frontend/cypress/e2e/taskLists.spec.ts的天然数据源三种形态搭配普通文档DOCUMENT、幻灯片SLIDE见 local_user_slide.md 中---与----的幻灯片/分支分隔符用法、游客可见笔记guest_note.md分别覆盖不同的渲染与权限场景扩展新种子笔记在notes/目录新增 Markdown 文件然后在 03_note.ts 中仿照userNoteContent的读取、元数据提取与表插入三段式追加即可无需改动任何其他代码。总而言之local_user_note.md是理解 HedgeDoc“笔记内容 → 元数据解析 → 多表落库 → 前端渲染”全链路的最佳起点它既是开发联调的数据资产也是研究 frontmatter 规范、revision 结构、author 溯源与权限模型的活样本。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐F3工具3分钟识别假U盘保护你的数据安全F3工具3分钟识别假U盘保护你的数据安全 你是否曾经怀疑过自己购买的U盘或SD卡容量是否真实在数字存储设备市场虚假容量产品泛滥成灾这些设备通过软件修改开发工具存储测试Querybook实战教程从零开始构建数据仪表板Querybook实战教程从零开始构建数据仪表板 Querybook是一款强大的大数据查询UI工具它将表格元数据与简洁的笔记本界面相结合让数据分析师和开发在 Fleet 本地开发环境批量生成种子数据用户、团队与测试主机的完整实战指南在 Fleet 本地开发环境批量生成种子数据用户、团队与测试主机的完整实战指南 在开发 Fleet开源设备管理平台时无论是测试权限模型、演练 E2E 用后端前端企业应用运维网络安全上一篇如何快速掌握Notion-py从安装到生产的完整指南下一篇如何利用UnityLibrary的2D相机系统打造完美像素游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
HedgeDoc 种子数据解析：local_user_note.md 与开发环境测试笔记的生成机制
后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载本指南以 HedgeDoc 仓库中backend/src/database/seeds/notes/local_user_note.md为核心剖析一条“种子笔记seed note”的完整生命周期从 Markdown YAML frontmatter 的书写格式到 Knex 种子脚本如何将其解析、落库为 note、revision、tag、author 等关联数据再到本地测试用户test/test123如何借助这些数据完成登录与 API 调试。读完你将掌握 HedgeDoc 开发环境种子数据的全貌并能自行编写、扩充属于自己的测试笔记与幻灯片。一、local_user_note.md 在 HedgeDoc 中扮演什么角色HedgeDocIdeas grow better together的仓库采用 pnpm workspace 组织为backend、frontend、commons、database等多个包。其中backend/src/database/seeds/目录存放的是仅供开发与测试环境使用的数据库种子数据用于在初始化数据库后立刻填充一批可交互的用户、笔记和 API Token方便开发者在前端与后端联调时直接使用而不必手工创建内容。backend/src/database/seeds/notes/local_user_note.md就是这批种子中的一份普通文档类型DOCUMENT测试笔记它的完整内容如下--- title: Local Test User Note 1 description: A test note for the local test user tags: - user - note --- # Title Some Text - [ ] Write A ToDo-List - [ ] Check some items这份文件同时承载了两层信息YAML frontmatter顶部---包裹区域声明笔记的标题、描述与标签元数据Markdown 正文一段包含一级标题、正文和待办清单Task List的示例内容用于验证文档渲染与待办交互。与它同目录的还有两份姊妹文件guest_note.md游客用户测试笔记和 local_user_slide.md本地测试用户的幻灯片演示文档三者共同构成种子笔记的三个典型形态。二、frontmatter 语法种子笔记的元数据规范local_user_note.md的 frontmatter 使用了三个字段title、description、tags。这三个字段并非随意约定而是对应 HedgeDoc 统一的笔记 frontmatter 解析规范其底层 Schema 定义在 commons/src/note-frontmatter/note-frontmatter.ts 中。完整可用的 frontmatter 字段包括均由 zod Schema 校验并带有默认值字段类型默认值说明titlestring笔记标题descriptionstring笔记描述tagsstring[][]标签列表用于 explore探索页面过滤typeDOCUMENT/SLIDEDOCUMENT使用的渲染器类型robotsstringrobots meta 标签内容langISO 639-1 枚举en笔记语言dirLTR/RTLLTR文字书写方向breaksbooleantrue是否将换行视为换段licensestring追加到 HTML 的版权声明头opengraphrecord{}OpenGraph meta 标签slideOptionsrecord见 default-note-frontmatter.tsReveal.js 幻灯片选项如transition: zoom、autoSlide: 0解析管线位于 commons/src/note-frontmatter/parse-note-frontmatter.ts先用js-yaml的load把 YAML 文本解析为对象再交给NoteFrontmatterSchema.safeParse做类型校验。若解析失败或字段非法则回退到默认 frontmatterdefaultNoteFrontmatter保证笔记依然可用。Schema 使用.passthrough()因此未被列出的自定义字段会被保留但忽略——这也是种子笔记只需要写三个字段就能工作的原因。三、种子脚本如何消费这份 Markdown 文件真正把local_user_note.md变成数据库记录的是 backend/src/database/seeds/03_note.ts。该脚本以seed(knex)为入口执行过程分为四个阶段1. 清空既有数据保证幂等await knex(TableNote).del(); await knex(TableAlias).del(); await knex(TableRevision).del(); await knex(TableRevisionTag).del(); await knex(TableAuthorshipInfo).del(); await knex(TableNoteGroupPermission).del(); await knex(TableNoteUserPermission).del();种子脚本可重复执行Knex seed 天然支持每次运行前先把与笔记相关的 7 张表清空避免重复数据污染。2. 读取 Markdown 文件并提取元数据const userNoteContent readFileSync(./notes/local_user_note.md, utf-8); const { title: userNoteTitle, description: userNoteDescription, tags: userNoteTags, } extractRevisionMetadataFromContent(userNoteContent);注意readFileSync的相对路径以backend/为基准种子目录下执行读取后交由extractRevisionMetadataFromContent处理。该函数的实现位于 backend/src/revisions/utils/extract-revision-metadata-from-content.ts它内部完成了用extractFrontmatter切分出 frontmatter 与正文调用parseNoteFrontmatter得到结构化的NoteFrontmatter通过generateNoteTitle生成标题——优先取 frontmatter 的title若为空则用extractFirstHeadingFromContentmarkdown-it 渲染 HTML 后提取第一个h1兜底提取description缺省为与tags缺省为[]并根据type字段得出NoteType。这正是种子笔记与运行时真实笔记走完全相同的元数据解析链路的体现种子数据不是“写死的数据库行”而是与真实创建笔记一致的解析产物。3. 写入 notes / aliases / revisions 主数据脚本按固定顺序插入三份笔记对应guest-note、user-note、user-slide三个主别名其中local_user_note.md对应userNoteAlias user-noteowner 为本地测试用户ownerId: 2版本号为 2publiclyVisible: false。随后为每份笔记创建 revision其中[FieldNameRevision.uuid]: userNoteRevisionUuid, [FieldNameRevision.patch]: createPatch(userNoteAlias, , userNoteContent), [FieldNameRevision.content]: userNoteContent, [FieldNameRevision.noteType]: NoteType.DOCUMENT, [FieldNameRevision.title]: userNoteTitle, [FieldNameRevision.description]: userNoteDescription,content直接保存整份 Markdown 原文patch通过diff包的createPatch(alias, , content)生成从空内容到全文的差异补丁这是 HedgeDoc 增量同步的基础数据结构noteType取NoteType.DOCUMENT对应 frontmatter 中未声明type字段时的默认文档类型可见 local_user_note.md 中确实没有写type正依赖默认值。4. 写入 tags、authorship 与权限关联数据脚本接着把解析出的标签user、note逐条插入TableRevisionTag关联到userNoteRevisionUuid随后在TableAuthorshipInfo中记录该 revision 的整段内容startPosition: 0到endPosition: content.length归属作者authorId: 2本地测试用户这是“谁写了哪段文字”的溯源信息最后写入组权限与用户权限TableNoteGroupPermission组 1 对 note 2 不可编辑canEdit: falseTableNoteUserPermission用户 2 对 note 2、3 可编辑canEdit: true。至此一份纯文本的 Markdown 种子笔记被完整物化为 note、alias、revision、revision-tag、authorship-info、group-permission、user-permission 七张表的关联数据。四、与之配套的本地测试用户与登录凭证local_user_note.md归属的ownerId: 2其用户信息由 backend/src/database/seeds/01_user.ts 定义用户名test显示名Local Test User作者样式authorStyle: 2登录身份AuthProviderType.LOCAL本地用户名密码方式密码哈希hashPassword(test123)的结果也就是说在开发环境运行种子后你可以直接用用户名test、密码test123登录 HedgeDoc然后通过主别名user-note访问这份种子笔记。同脚本还创建了游客用户Guest 1guestUuid固定对应guest-note笔记。此外backend/src/database/seeds/02_api_token.ts 为test用户预置了一个有效期为一年的 API Tokenlabel 为Local Test User API Tokensecret 以 SHA-512 哈希存储可用于直接调用 backend 的私有 API 做接口调试例如配合 e2e 测试套件backend/test/private-api使用。五、如何运行种子Knex 命令与开发数据库配置种子的执行由 Knex 驱动。开发环境的数据库配置在 backend/knexfile.tsdevelopment: { client: better-sqlite3, connection: { filename: ./hedgedoc.sqlite }, useNullAsDefault: true, migrations: { directory: ./src/database/migrations }, seeds: { directory: ./src/database/seeds }, }开发库默认使用better-sqlite3单文件数据库hedgedoc.sqlite种子目录指向src/database/seeds。backend 的 package.json 为此提供了便捷脚本backend/package.jsonnpm run knex -- seeds:run实际展开为tsx ../node_modules/.bin/knex --migrations-directory src/database/migrations --knexfile ./knexfile.ts seeds:run。运行前请先执行迁移npm run knex -- migrate:latest迁移脚本位于 backend/src/database/migrations/20250312211152_initial.js在应用启动时也会由 backend/src/migrate.ts 自动检查并执行。种子脚本的执行顺序依赖 Knex 对文件名的排序01_user.ts→02_api_token.ts→03_note.ts确保先有用户与 Token再创建笔记因此你可以放心地反复seeds:run——每份种子文件都会先清空对应表再插入。六、从种子笔记到真实笔记模板参考与扩展建议local_user_note.md虽然只有十几行却是一份“最小可用的 HedgeDoc 笔记”范本值得复用的要点包括frontmatter 写最小集titledescriptiontags即可其余字段type、lang、breaks、slideOptions等都有默认值按需补充正文验证交互能力- [ ]待办清单在 HedgeDoc 前端会被渲染为可勾选的 Task List相关渲染插件见 markdown-it-plugins/src/task-lists种子笔记因此也是前端 cypress 测试frontend/cypress/e2e/taskLists.spec.ts的天然数据源三种形态搭配普通文档DOCUMENT、幻灯片SLIDE见 local_user_slide.md 中---与----的幻灯片/分支分隔符用法、游客可见笔记guest_note.md分别覆盖不同的渲染与权限场景扩展新种子笔记在notes/目录新增 Markdown 文件然后在 03_note.ts 中仿照userNoteContent的读取、元数据提取与表插入三段式追加即可无需改动任何其他代码。总而言之local_user_note.md是理解 HedgeDoc“笔记内容 → 元数据解析 → 多表落库 → 前端渲染”全链路的最佳起点它既是开发联调的数据资产也是研究 frontmatter 规范、revision 结构、author 溯源与权限模型的活样本。赞分享后端前端云原生【免费下载链接】hedgedocHedgeDoc - Ideas grow better together项目地址https://gitcode.com/gh_mirrors/he/hedgedoc点击查看免费下载相关推荐F3工具3分钟识别假U盘保护你的数据安全F3工具3分钟识别假U盘保护你的数据安全 你是否曾经怀疑过自己购买的U盘或SD卡容量是否真实在数字存储设备市场虚假容量产品泛滥成灾这些设备通过软件修改开发工具存储测试Querybook实战教程从零开始构建数据仪表板Querybook实战教程从零开始构建数据仪表板 Querybook是一款强大的大数据查询UI工具它将表格元数据与简洁的笔记本界面相结合让数据分析师和开发在 Fleet 本地开发环境批量生成种子数据用户、团队与测试主机的完整实战指南在 Fleet 本地开发环境批量生成种子数据用户、团队与测试主机的完整实战指南 在开发 Fleet开源设备管理平台时无论是测试权限模型、演练 E2E 用后端前端企业应用运维网络安全上一篇如何快速掌握Notion-py从安装到生产的完整指南下一篇如何利用UnityLibrary的2D相机系统打造完美像素游戏体验创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
