Ivan's Blog
主题

Markdown style

Markdown style 定义 Markdown 源文件的正文排版、格式化和 Git 自动修复惯例。默认每个自然段保持一行，使用 Markdown 语法表达必要的结构；软换行由官方 formatter 合并，显式硬换行保留语义。它提供可重复的源文件样式，而不是要求作者按固定字符数拆分内容（dprint.json、docs/specs/markdown-style/SPEC.md）。

  • 工具
  • 文档

目录

Definition

Markdown style 定义 Markdown 源文件的正文排版、格式化和 Git 自动修复惯例。默认每个自然段保持一行，使用 Markdown 语法表达必要的结构；软换行由官方 formatter 合并，显式硬换行保留语义。它提供可重复的源文件样式，而不是要求作者按固定字符数拆分内容（dprint.json、docs/specs/markdown-style/SPEC.md）。

本主题不负责文档业务内容、链接可达性或站点视觉设计；与 Quality gates 的边界是：本主题确定具体排版和修复行为，后者确定这些检查如何参与 merge/readiness contract。可安装实现位于 skills/policies/markdown-style/，Topic 只维护可复用知识，不复制其工具资产。

When to use

项目准备统一 Markdown formatter、修复非语义正文换行、接入 staged auto-fix，或要求本地与 CI 使用相同样式配置时命中。若只修改文档内容或调整文档站 UI，且没有改变源文件排版与 Git/CI 契约，就不应扩大到此主题（docs/specs/markdown-style/SPEC.md）。

采用前检查当前 hook 管理器、部分暂存习惯和现有 CI。工具接入应保留已存在的 hook、配置、未暂存内容及 required check 名称；当前仓库从 repo-owned 原生配置开始，其他项目通过独立的 Policy adoption preview 接入（skills/policies/markdown-style/SKILL.md）。

Habits / defaults

  • 默认使用原生 dprint 的官方 Markdown 插件；textWrap: never 配合 wrapUnspacedScripts: true 合并中英文软换行，不引入正文行宽上限（dprint.json）。
  • 段落由空行分隔。列表层级、表格内容、代码块、frontmatter 和显式硬换行是需要保留的结构，不使用文本替换来猜测它们的边界（docs/specs/markdown-style/SPEC.md）。
  • 表格紧凑填充，代码块与 HTML 跳过内嵌 formatter，硬换行统一为反斜杠，换行符使用 LF；固定工具版本和 SHA256 由可复用包清单管理（skills/policies/markdown-style/assets/toolchain.json）。
  • 提交只修复 staged Markdown，使用 Lefthook 原生部分暂存恢复和 stage_fixed: true。初始化完成下载与 Wasm 编译，提交阶段只使用本地工具；缺失时明确失败并提示 setup（lefthook.yml、tools/markdown.py）。
  • CI 使用与本地相同的 check，现有文档机械格式化单独提交。生成器直接产出合规 Markdown，先确定最终文本再计算 fingerprints，避免 formatter 和生成器互相覆盖（tools/topic_skill_manager.py）。

Reference implementations

  • dprint.json、lefthook.yml、tools/markdown.py：提供方仓库统一配置、暂存修复和全仓只读检查的实现面。
  • skills/policies/markdown-style/SKILL.md 与 package assets：供其他项目预览并明确采用的自包含工具包，包装同时支持提供方源包和项目安装面。
  • projects/tps55288-rs.md：已有项目记录了 dprint 与 Lefthook 的原生工具组合；该快照仅作为工具组合样本，不证明其已采用本主题的正文配置。
  • docs/specs/markdown-style/SPEC.md：保留部分暂存、恢复冲突、生成稳定性和 CI 一致性的长期行为契约。

Failure modes

  • 仅关闭长行 lint，却继续由 formatter 按列宽拆行：需要检查实际 Markdown textWrap，不能只从 lineWidth 推断正文行为（dprint.json）。
  • 只设置 never，中文仍保留软换行：官方插件对无空格脚本还有独立开关，应显式启用 wrapUnspacedScripts 并用中文 fixture 验证（skills/policies/markdown-style/assets/templates/dprint.json）。
  • 格式化工作区后直接全量 git add，会把未准备的修改一起提交：应让 hook 选择 staged 文件并使用原生备份与恢复；冲突时中止提交，保留修改和恢复入口（lefthook.yml）。
  • 提交时临时安装工具，造成网络等待或版本漂移：把固定版本下载、摘要校验和 Wasm 编译放在 setup，hook 缺失工具时清楚失败（skills/policies/markdown-style/assets/scripts/markdown.py）。
  • 生成器输出与格式基线不一致，重建后不断产生差异：修正模板的标题空行和表格填充，并验证重复生成正文与 tree hash 稳定（tools/topic_skill_manager.py）。

Evidence index

  • dprint.json
  • lefthook.yml
  • tools/markdown.py
  • tools/topic_skill_manager.py
  • skills/policies/markdown-style/SKILL.md
  • skills/policies/markdown-style/assets/toolchain.json
  • docs/specs/markdown-style/SPEC.md
  • projects/tps55288-rs.md
  • https://github.com/dprint/dprint-plugin-markdown/blob/0.26.0/tests/specs/Text/Text_UnspacedScripts_TextWrap_Never.txt
  • https://github.com/evilmartians/lefthook/releases/tag/v2.1.16

相关内容