plexy-markdown

plexy-markdown

紧凑的 Markdown 扫描速度快，差异也清晰。每行表达一个观点，其余内容用嵌套结构呈现。

格式

• 每个项目符号只表达一个陈述。
  • 陈述是一个独立的主张、步骤、事实或规则。
  • 如果项目符号用“和”“然后”“其中”或破折号连接了两个观点，就把它们拆开。
• 子陈述写成子项目符号。
  • 用嵌套结构展现层次：父项点明主题，子项加以描述。
  • 两到三层就足够；层级更深说明结构有问题。
• 每行不超过 120 个字符。
  • 这项限制是为了保证可读性，不是格式规则。
  • 在分句处拆分，用子项目符号呈现，再考虑换行。
• 保持简洁。
  • 删去不影响含义的词语（非常、确实、为了、值得注意的是）。
  • 删除填充性标题和空洞的过渡语。

示例

不佳 — 一个长项目符号混杂了多个观点：

部署流水线会构建镜像、推送到注册表、更新清单，并验证 Pod。

良好 — 父项加子项：

- The deploy pipeline has four stages.
    - Build the image.
    - Push it to the registry.
    - Update the manifest to trigger a rollout.
    - Verify the pods are healthy.

不佳 — 用破折号串联片段：

• 服务速度很快 - 它会缓存响应 - 并在失败时重试。

良好：

• 服务速度很快。
  • 它会缓存响应。
  • 它会在失败时重试。

规则的例外

• 代码块、表格、frontmatter 和 URL 不受限制。
  • 换行可能破坏代码、URL 或表格单元格。
  • 宁可让这些行超长，也不要破坏内容。
• 不要为了满足行宽限制而删除内容。
  • 调整结构并改用子项目符号；确实很长的单个陈述可以保留原样。
• 不要改写用户没有要求你修改的文字。
  • 对你编写或编辑的内容应用此风格，不要改动无关文件。
• 保留文档现有结构。
  • 不要仅仅为了使用项目符号，就合并标题、表格或有序步骤。

原因

• 每行一个观点，读者只需浏览开头几个词，就能了解内容结构。
• 短行适用于较窄的终端，也便于并排查看差异。
• 子项目符号能表达父项与细节之间的关系，而散文往往会掩盖这种关系。
• 紧凑的项目符号占用更少令牌，也能避免每次编辑都产生合并冲突。