版本控制后端【免费下载链接】loreLore is a next-generation, open source version control system项目地址https://gitcode.com/gh_mirrors/lore6/lore点击查看免费下载Lore 项目为所有 Markdown 文档制定了统一的“页面形状page shape”标准本文即是对 docs/developing/doc-standards/canon/format.md 的完整解读它规定了页面在标题、列表、表格、加粗/斜体/代码、Callout 提示块、按键组合等方面的具体写法。无论你是为 Lore 贡献新文档、评审既有页面还是将旧文档整改为符合规范的形态读完本文都能掌握一套可落地、可被 Vale 等工具自动校验的编写规则并理解 Lore 文档在 GitHub 与 Material for MkDocs 双渲染面上的取舍逻辑。规范体系的定位format 是“页面形状”那一半Lore 的文档规范docs/developing/doc-standards/README.md把规则拆成三个 canon 文件职责互不重叠文件管什么canon/doc-types.md七种文档类型Tutorial、How-To、Reference、Explanation、Internals、ADR、Code-Standard与 Landing 页canon/language.md“页面上放什么词”语气、语态、代词、用词、品牌命名、链接约定canon/format.md“页面长什么样”标题、列表、表格、加粗/斜体/代码、Callout、按键组合当两条规则冲突时按 doc-standards/README.md 的 authority 层级裁决doc-types.mdlanguage.md与format.mdoperational/。也就是说format 规范处于文档标准的第二优先级仅次于文档类型定义。新增文档前建议先走一遍 writing-a-doc.md 的十分钟入门流程评审时则对照 operational/review-checklist.md 逐项自查。标题层级、大小写与平行结构层级Hierarchy每个页面只能有一个 H1它是页面标题采用 sentence case。H1 保证了 GitHub、编辑器、渲染站点三种阅读载体上都有一眼可见的标题。正文默认从H2起子章节用 H3。避免 H4除非主题确实需要第四级不要用 H5、H6。深层标题树会让右侧目录TOC变得不可读——如果某个小节需要 H4 甚至更深说明它已经长到应该拆成独立页面了。注意这里还有一个 markdownlint 的结构约束MD025单页只能有一个 H1会同时扫描 YAML frontmatter 的title因此项目的 .markdownlint-cli2.jsonc 配置把front_matter_title设为空让规则只强制“正文里一个 H1”避免与 frontmatter 标题误报冲突。大小写一律 sentence case所有标题使用句子式大小写首词与专有名词大写其余小写。正确## Stage and commit files正确## Configure the Lore CLILore 是专有名词CLI 是缩写错误## Stage and Commit Files这条规则由 Vale 规则 Lore.Headings 强制它基于capitalization检查器、作用域限定在 heading并按$sentence匹配indicators里的:表示带冒号的标题同样要遵守。规则维护了一串例外词表ADR、CLI、Git、Lore、macOS、MkDocs、Windows 等确保专有名词不会被误改小写。平行结构Parallel construction同一层级的兄弟标题应共享同一语法形态——统一用动名词、祈使句或名词短语并在同级间保持一致!-- 正确全部动名词 -- ## Cloning a repository ## Branching from main ## Merging into main!-- 正确全部祈使句 -- ## Clone a repository ## Branch from main ## Merge into main!-- 错误混合 -- ## Cloning a repository ## How to branch ## Merge标题是路标不是摘要标题保持简短。不要把括号里的缩写全称塞进标题——要么用缩写要么用全称然后在正文首次出现处展开正确## Continuous integration错误## Continuous integration (CI)分段Chunking用留白提升可扫读性密集堆砌的文字难以扫读空白能提高可读性。具体手段短段落、简单句子、列表、表格。偏好短而简单的句子。一个句子里出现两个以上逗号就是需要拆分的信号。不要用and、or、but连接两个以上的短语或分句。这一节没有 Vale 强制靠作者自觉但 markdownlint 的MD013行长度在 Lore 配置里被显式禁用tools/README.md 的 Rule choices 表原因是“Lore 文档不强制硬换行散文按编辑器宽度自动回绕”。列表无序与有序的选用规则列表分两种项目符号无序与编号有序。顺序无关时用无序列表。顺序重要时用有序列表。每个条目都有同一组属性时用表格。条目少于三个且顺序自然流动时直接用散文。无序列表规则每个条目的首词大写。引导句以冒号结尾。只要有一个条目是完整句子所有条目都以句号结尾若都不是完整句子则省略句末标点。条目结尾不用分号或逗号——要么句号要么没有。尽量让所有条目以同一词性开头。每个条目要么全是完整句子要么全是句子片段不要混用。条目长度应相近。一个两词条目紧挨着一个段落级条目说明这个列表在干两件不同的活。标题式条目加粗 冒号或破折号把引导术语加粗用冒号:或破折号—与解释隔开不要用连字符!-- 正确 -- - **Commit:** A snapshot of the repository at a point in time. - **Branch —** A movable pointer to a commit.!-- 错误 -- - **Commit** - snapshot编号列表规则任何三步到十步的操作步骤用编号列表。少于三步用散文或无序列表。超过十步在编号父步骤下拆分子步骤或拆成多个主题。每个步骤首词大写。除非所有步骤都是句子片段否则每个步骤都以句号结尾。每个步骤以祈使动词开头Run、Open、Set。表格始终包含表头行。加粗最左列的关键术语这是读者最先扫读的行标签。例外如果该术语是命令、变量或函数名改用代码格式反引号而不是加粗。单元格内容保持简短。如果某个单元格需要写段落说明这个表格形态不对——应该改成每个条目一个小节。表格只用于表格化数据不用于布局。| Setting | Description | Default | | ------------------- | -------------------------------------------------------------- | --------- | | **Auto Connect** | Connect to the default server automatically on open. | false | | **Default Server**| Server URL the system tries to connect to on **Go Live**. | none |markdownlint 会从结构上守护表格MD056检查各列数量是否一致tools/README.md。加粗Bold加粗用于UI 元素名——按钮名、菜单项、选项名。击键Press **Esc**.表格与散文中的选项名。默认值名称。菜单路径——整体加粗、用分隔**File Preferences Editor**。表格中的关键术语通常是最左列。正文中首次引入的新术语。不要加粗正文中的 Lore 产品名。链接——Markdown 链接样式是内建的不需要再加粗。斜体Italics斜体只有三种合法用途引用书籍或外部作品的标题页面上首次引入的术语与加粗二选一同一文档内保持一致第三方文档中被引用的外语词或标题名。不要用斜体或引号做一般性强调请用加粗正确The **read-only** flag prevents writes.错误The read-only flag prevents writes.下划线Underline绝不使用。下划线留给超链接渲染器会自动为链接加下划线样式。代码格式Code formatting所有代码示例使用带语言标签的围栏代码块bash lore stage src/main.rs lore commit Add main entry point 语言标签选择规则bash读者要运行的 shell 命令。console交互式终端会话同时显示提示符与输出。text纯输出没有可执行命令。行内代码片段单个反引号用于命令名lore status、文件路径~/.config/lore/config.toml、flag 名--force、环境变量LORE_HOME、函数名、选项键。不要对代码加粗或斜体。不要把产品名Lore或 UI 元素名包进代码片段——UI 元素用加粗产品名用普通文本。不要把文字烤进代码截图永远用代码块绝不截图终端。对应地markdownlint 的MD040围栏必须有语言标签、MD046禁用缩进代码块一律用围栏、MD048围栏符号一致会从结构上强制这些约定tools/README.md。Callout 与警示块只用五种 GFM 原生类型Lore 文档使用GitHub Flavored Markdown 的 alert 语法即引用块加[!类型]前缀。共五种 GFM 原生类型按内容匹配类型何时使用决策规则TIP可选的捷径、生产力提示或锦上添花的背景。读者跳过它毫无损失。内容有帮助但非必需。NOTE属于本页但会打断行文的有用背景。读者看到它有好处但没有它页面也能成立。内容提供信息——既非可选也非必需。IMPORTANT读者要完成任务必须吸收的信息。跳过会导致失败或困惑但不会造成损失。内容是成功所必需的。CAUTION带有可恢复负面后果或不明显的副作用的操作。在读者行动之前先提醒。内容描述可恢复风险——行动前三思。WARNING会导致数据丢失、安全暴露或其他不可恢复损害的操作。读者必须遵从。内容描述不可恢复风险。自上而下的决策树是否涉及损害风险否 →TIP可选、NOTE提供信息或IMPORTANT成功必需。是 →CAUTION可恢复或WARNING不可恢复。是否任务成功所必需是 →IMPORTANT。否 → 读者看了受益用NOTE可跳过用TIP。后果可恢复吗是 →CAUTION。否 →WARNING。五种类型的写法示例 [!TIP] Use lore history --oneline to scan a branchs recent revisions. [!NOTE] Lore revisions are content-addressed. The hash signature is computed from the content, so two identical revisions share one signature. [!IMPORTANT] Run lore sync before branching, or your new branch will start from a stale revision and the merge will conflict against current state. [!CAUTION] lore branch archive removes the local branch pointer. Unmerged revisions remain reachable through the reflog for 30 days, after which garbage collection prunes them. [!WARNING] lore reset --hard discards uncommitted changes. There is no undo.两条硬性禁止均有 Vale 强制不要用INFO或DANGER——它们不是 GFM 原生类型GitHub 上不会渲染。Vale 规则 Lore.AlertTypes 会把 [!INFO]与 [!DANGER]标记为 warning并在消息里指向本文档的 Callout 小节。不要用旧版 MkDocs 的!!! note/!!! tip/!!! warning语法——它在 GitHub 和编辑器里不渲染还把文档锁死在某一个静态站点生成器上。Vale 规则Lore.MkDocsAdmonitions将其标记为 error。此外不要把承载关键信息的操作说明或警告藏进折叠collapsible区块里。内容要与类型匹配——一个其实是 TIP 的 WARNING 会“狼来了”把 IMPORTANT 用在纯锦上添花的背景上会稀释真正重要的提示。在两个相邻类型之间拿不准时NOTEvsIMPORTANT、CAUTIONvsWARNING选不那么刺眼的那个——升级警报只有在保留使用时才有意义。Material for MkDocs 特性双渲染面的取舍Lore 文档在两种表面渲染GitHub原始 Markdown和用Material for MkDocs主题发布的站点站点配置见 mkdocs.yml。默认原则是使用两边都能正常工作的语法——这正是上面 Callout 一节强制 GFM alert 而不是 Material 的!!! note的原因。本小节只覆盖少数几个值得越过默认、使用 Material 独有特性的窄场景。主题启用了什么mkdocs.yml 启用了一小撮扩展与主题特性影响写作的有特性扩展或主题开关能给你什么GFM alert 渲染gfm_admonition在解析期把 [!NOTE]/ [!IMPORTANT]/ [!WARNING]等转换成 Material 警示框。Callout 要在发布站点渲染成样式化色块就靠它markdown-gfm-admonition包。内容标签页pymdownx.tabbed同一内容的并排变体例如按平台区分的安装步骤。用下面讲的注释约定编写构建时由content_tabs.py钩子转换。可折叠区块pymdownx.details???与???折叠块。富代码围栏pymdownx.superfences列表、标签页、警示框内的嵌套围栏。代码复制按钮content.code.copy每个代码块加复制图标。免费无需改语法。代码注解content.code.annotate指向代码块内某行的编号 Callout。HTML 属性attr_list通过{ .class #id }给元素加类与 ID。Markdown 内嵌 HTMLmd_in_html让div块内的 Markdown 仍按 Markdown 解析。其中几个在 GFM 没有对应物、GitHub 上不渲染。复制按钮和代码注解是“免费”的——它们在 GitHub 上对读者零成本因为语法本身不可见。而标签页、折叠块和attr_list会实质改变源码需要斟酌。何时才值得用 Material 独有特性问自己没有它这篇文档会变差吗如果替代方案是冗长的并行小节结构、难以扫读的列表或三份近乎重复的步骤Material 特性就值得使用如果替代方案只是一条短列表那纯 Markdown 胜出。一个反面例子是 CalloutGFM alert 在两种表面都渲染、且优于!!! note所以那条规则是封闭的见上一节。标签页现在也封闭了下面的注释约定在两种表面都渲染干净因此源码中禁用裸 ...语法Vale 规则Lore.MkDocsTabs强制。内容标签页Content tabs注释分隔约定标签页用于读者只会选取其中之一的平行内容按平台的安装步骤、按语言的代码示例、按读者群体的走查。读者只选一个标签页其余保持隐藏。标签页用注释分隔约定编写绝不用裸 ...语法ValeLore.MkDocsTabs强制。GitHub 把注释渲染为无内容、把加粗标题行渲染为普通粗体所以源码在两种表面都可读站点构建时由 docs/assets/hooks/content_tabs.py 钩子把每组转换为 Material 标签页!-- tabs:start -- !-- tab -- **macOS** bash curl -Lo lore https://example.com/lore-macos !-- tab -- **Linux** bash curl -Lo lore https://example.com/lore-linux !-- tabs:end --从钩子源码content_tabs.py可以看到它如何工作每个组被缓冲直到完整且格式正确才转换_scan_fence会跟踪围栏代码块状态确保代码块里的标记文本永远是内容、不是标记。钩子对每组做构建期校验格式错误的组原样保留并输出 warning而mkdocs build --strict会把 warning 视为致命错误。具体约束如下!-- tabs:start --、!-- tab --、!-- tabs:end --各自独占一行且缩进一致在列表步骤内则为该列表的内容缩进。每个!-- tab --之后紧跟该标签页标题一行只含加粗文本的行如**macOS**。标题不能包含双引号或星号_render_group中会分别对和*判为 malformed。没有前置!-- tab --的纯加粗行是普通内容绝不会开启新标签页。一个组至少包含两个标签页。内容按自然缩进编写——不需要额外四空格缩进代码围栏保持普通围栏。不要把承载关键信息的说明藏在标签页里。一个需要看所有平台的读者例如在 macOS 上开发、却要在 Linux 上配 CI不该为了找出“哪些内容相同、哪些不同”而逐个点击——如果超过一半的步骤在各标签页间重复把共享步骤抽出来只对分歧部分做标签页。调研更高级的能力Material 频繁发布新特性训练数据容易滞后。需要本规范未覆盖的特性时项目推荐的流程是用context7MCP 读当前文档而不是凭猜测调用resolve-library-idlibraryName: Material for MkDocs得到 Context7 ID。调用query-docs带上该 ID 和具体问题——例如How do content tabs work with nested code blocks?或What does content.code.annotate enable and how are annotations written?。Material 里大部分富 Markdown 语法来自 PyMdown Extensions标签页语法、折叠块、snippets、superfences 都在那里问“语法本身怎么工作”时查该库而不是问 Material 怎么给它加样式。在往文档里加新的 Material 独有特性前先检查本文件前面覆盖的 GFM 友好语法是否已经够用——双渲染默认偏好仍然优先。连字符Hyphenation名词前的复合修饰语——要连字符Lore is a large-scale project.、The team prefers user-centric features.以 -ly 结尾的复合词——不要连字符-ly本身已经表明修饰关系正确closely related branches、fully qualified path错误closely-related branches、fully-qualified pathVale 规则Lore.HyphenLy强制。这条规则在 tools/README.md 中被列为“会捕获fully-qualified这类被错误连字符化的-ly副词复合词”。名词后的复合词——默认不加连字符The project has a large scale.、The features are user-centric.破折号家族em dash、en dash、hyphenLore 文档在em 与 en dash 两侧加空格符号宽度用途间距Em dash—一个m的宽度引出解释性文字替代段落、逗号、冒号前后各一个空格En dash–半个 em数字与日期范围前后各一个空格Hyphen-键盘宽度复合词不适用连字符不能替代 em dash、en dash 或冒号。[!NOTE] Lore 使用带空格的 em 与 en dash——带空格的破折号在比例字体下读起来更好在编辑器和渲染站点上也能跨行宽可预测地回绕。因此.vale.ini禁用了Lore.Dashes这条规则。这也是 tools/README.md 中明确记录的“Lore 与 Microsoft Writing Style Guide 的两处分歧”之一另一处是 language.md 中的项目口吻we。按键组合Key combinations描述按键组合时前后各留一个空格正确Ctrl C、Alt Shift Enter错误CtrlC、AltShiftEnter首次引入不常见或含义模糊的键时拼写出它的名称the backtick () key。键盘键名Keyboard keys使用美式键盘上印制的拼写。大多数键是首字母大写、其余小写Esc、Ctrl、Shift、Alt、Tab、Enter。Shift、Hyphen及任何含义模糊的键要拼写完整。Space bar是两个单词。符号与字符Symbols and characters符号含义—Em dash–En dash©版权符号®注册商标符号™商标符号°度符号描述组合键时少见的键盘名称键名称~tildebacktick[ ]left and right brackets{ }left and right curly brackets也叫 curly braces left and right angle brackets^caret*asteriskampersand/slash也叫 forward slash\backslash\|pipe也叫 vertical bar跨页面内容复用Reusing content across pages同一内容出现在两个以上页面时把它提炼为单一事实来源source-of-truth页面并在其他页面链接过去只出现一两次时直接内联。内联与链出二选一并在整个文档集内保持一致。这与整个 doc-standards 目录的设计一脉相承doc-types.md、language.md、format.md三个 canon 文件本身互为链接、各司其职避免规则文本在多个页面重复维护。用工具链把规范变成可执行检查format.md 中的许多规则并非“建议”而是有自动化强制手段的。规范对应的工具链在 tools/README.md 完整文档化发布前的标准命令是bash scripts/docs-lint.sh该脚本按序运行三个 linter即使某个失败也会继续跑完其余工具最后输出每项的passed/FINDINGS/ERRORED/missing汇总。其中与 format 规范直接相关的强制规则包括规则捕获内容严重度依据Lore.Headings非 sentence case 的标题warningformat.md § 标题大小写Lore.HyphenLyfully-qualified这类 -ly 副词复合词被连字符化warningformat.md § 连字符Lore.MkDocsAdmonitions旧版!!! note/!!! tip/!!! warning语法errorformat.md § CalloutLore.MkDocsTabs裸 ...标签页语法errorformat.md § 内容标签页Lore.AlertTypes非 GFM 的 [!INFO]/ [!DANGER]warningformat.md § CalloutMD013行长度显式禁用—规则选择表MD025单页多 H1配合front_matter_title调优—规则选择表另外内容标签页的构建期校验由 docs/assets/hooks/content_tabs.py 在mkdocs build时执行格式错误的组会让--strict构建失败。也就是说一条 format 规范从写作作者遵守→ 静态检查Vale / markdownlint / lychee→ 构建校验content_tabs.py 钩子形成了完整闭环作者可以在编辑器里实时看到 Vale 报错评审者用 operational/review-checklist.md 逐项核对最终发布前由 scripts/docs-lint.sh 全量把关。理解这套机制后你就能判断规范中哪些条目“写了就有人查”从而把注意力集中在真正会被机器校验、也真正影响读者阅读体验的格式决策上。赞分享版本控制后端【免费下载链接】loreLore is a next-generation, open source version control system项目地址https://gitcode.com/gh_mirrors/lore6/lore点击查看免费下载相关推荐Halo 富文本编辑器表格渲染契约解析从编辑器到主题端的统一渲染规范Halo 富文本编辑器表格渲染契约解析从编辑器到主题端的统一渲染规范 Halo 的文档型表格editor table经历了一次以“模型、视图、交互三层分离后端前端CMSMaterial UI 文档的 Callout 标记语法全解从 :::info 到 MuiCallout 渲染链路Material UI 文档的 Callout 标记语法全解从 :::info 到 MuiCallout 渲染链路 本文面向想要理解或复刻 MUI 文档「提示前端UI组件设计系统Biome Markdown 格式化器深度解析嵌套列表与 GFM 任务列表的格式化规则Biome Markdown 格式化器深度解析嵌套列表与 GFM 任务列表的格式化规则 导读 Biome 的 Markdown 格式化器 biome_mar开发工具Lint格式化静态分析代码质量前端上一篇【亲测免费】 终结网页转PDF内容截断难题 —— 开源解决方案深度剖析与推荐下一篇终极Web性能测试工具Boomerang从入门到精通创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考