NautilusTrader Markdown 风格规范基于 markdownlint 的文档编写与自动化校验指南【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader本文是 NautilusTrader 仓库内 Markdown 文档的编写基准baseline说明适用于所有在仓库文档范围内撰写、修改 Markdown 文件的开发者与 AI 协作场景。文章以 docs/developer_guide/markdown_style.md 为骨架结合仓库根目录的 .markdownlint.jsonc 配置、Makefile 中的check-markdown目标以及 scripts/check-markdown-tables.py 脚本完整讲解规则层级、语法基线、各类元素的书写要求、自动化强制机制与过渡性采用策略。读完本文你将能写出既符合 CommonMark/GFM 规范、又能通过本仓库 markdownlint 检查的文档并理解每一条规则背后的工具实现。规范定位一份可复制的共享基线markdown_style.md是一份标准修订版Standard revision: 1的共享 Markdown 基线文档设计目标是被多个采用该文档副本的仓库共同维护。因此它明确要求各仓库的副本必须与被维护的源逐字节byte-for-byte保持一致仓库特有的补充内容必须写在单独的本地指南中而不是混入共享基线。在 NautilusTrader 中这份仓库本地补充指南就是 docs/developer_guide/docs.md。docs.md 在开篇即声明markdown_style.md是 Markdown 语法与格式的共享基线.markdownlint.jsonc强制执行其机械子集而 docs.md 只覆盖 NautilusTrader 文档特有的约定文档类型体系、语气、MDX 组件、支持矩阵表格等不重复基线内容。这种共享基线 本地指南的分层结构既保证了跨仓库风格统一又为项目保留了定制空间。规则层级Required、Preferred 与 Transitional规范将每一条规则划分为三个层级理解层级是阅读全部规则的前提层级含义判定标志Required必需适用于范围内每个文件不满足即不合规无条件祈使句Use、Do not或含 must 的表述Preferred首选存在多种合法写法时的默认选择使用 Prefer 措辞不影响合规判定Transitional过渡仅适用于新增或大幅编辑的指定构造明确标注Transitional或描述为 transitional既有实例可保留至单独迁移此外规范对措辞的含义边界做了精确定义含 may 或 allowed 的表述授予有限许可而非义务任何限制该许可的条件都属于 Required仓库可以在其渲染器、生成内容或导入材料确有需要的场景下记录更窄的本地例外。语言与扩展CommonMark 为基GFM 为扩展规范对 Markdown 方言的选择非常明确以CommonMark作为基础规范使用GitHub Flavored MarkdownGFM来支持表格、任务列表、删除线和自动链接额外的 front matter、Markdown 扩展或渲染器组件仅当仓库有文档说明并支持时才可使用禁止引入依赖未文档化渲染器扩展的语法。规范还特意提醒文首链接的两个规范是参考资料而非常规前置条件——只有遇到本地指南、上下文内容和 markdownlint 都无法回答的具体解析器/渲染器歧义时才需要打开它们查阅。这也意味着绝大多数日常写作不需要翻阅规范原文。强制机制从配置文件到命令行风格规范本身是意图而自动化工具是其机械子集的执行者。仓库的强制链路由三层构成。1. 仓库级 markdownlint 配置仓库根目录的 .markdownlint.jsonc 采用默认全关default: false 显式开启的策略即只启用仓库确认需要的规则。已启用的规则及其配置覆盖了本规范的所有机械性要求例如MD001/heading-increment标题层级每次只能递增一级MD003/heading-styleATX 标题风格style: atxMD004/ul-style无序列表用-style: dashMD009/no-trailing-spaces禁止行尾空格br_spaces: 0同时禁止用尾随空格制造硬换行并启用strictMD012/no-multiple-blanks连续空行最多 1 行MD031/MD032围栏代码块与列表前后必须有空行MD034/no-bare-urls禁止裸 URLMD035/hr-style分隔线风格固定为---MD046/code-block-style代码块使用围栏风格fencedMD049/MD050强调与加粗统一使用星号*italic*、**bold**MD055/MD056/MD058表格必须有首尾竖线、列数一致、表格前后有空行MD059/descriptive-link-text链接文本必须具有描述性MD060/table-column-alignment表格列对齐风格为aligned。2. make check-markdown 目标Makefile 中的check-markdown目标把两条检查串联起来check-markdown: #-- Lint Markdown with markdownlint-cli2 and check table delimiter padding $(MARKDOWNLINT) --config .markdownlint.jsonc $(MARKDOWNLINT_FILES) python3 -B scripts/check-markdown-tables.py $(MARKDOWN_FILES)第一条命令用markdownlint-cli2配合.markdownlint.jsonc检查全部 Markdown 文件其版本通过 pre-commit hook 的 rev 固定Makefile 中从 pre-commit 配置解析MARKDOWNLINT_VERSION第二条命令运行 scripts/check-markdown-tables.py专门规整表格的列宽填充与分隔行内边距。3. pre-commit 钩子与生成文件normalize markdown table paddingpre-commit 钩子会自动把表格重写为规范要求的填充形式最宽单元格 两侧各一空格因此手写时无需人工数空格规范同时要求不要手工编辑生成的 Markdown应修改其源文件后重新运行生成器生成的、导入的第三方文档与渲染器夹具可使用文档化的仓库排除规则。4. 配置与规范冲突的处理规范给出了三条明确准则遵循仓库的.markdownlint.jsonc或等价本地配置将本规范视为预期风格将 markdownlint 视为其机械子集的自动化执行规范与本地配置之间存在未文档化冲突时视为需要解决的漂移drift而不是默认的例外确保仓库 lint 范围内所有作者编写的 Markdown 都通过配置的 Markdown 检查。标题ATX 风格与大小写约定使用 ATX 标题#、##、###等对应MD003每篇文档的第一个 Markdown 标题必须是唯一的 H1对应MD025/single-titleH1 使用 Title Case每个实词首字母大写H2 及以下使用 Sentence case仅首字母与专有名词大写保持逻辑层级不跳级对应MD001每个标题上下各留一个空行对应MD022lines_above: 1、lines_below: 1。docs.md 补充了本地约定无论标题层级专有名词产品名、技术名、公司名、缩写始终大写这一条优先于大小写规则。段落与换行段落之间用一个空行分隔不要出现连续空行对应MD012maximum: 1散文行长度目标为100–120 字符Preferred 级优先在自然断点换行避免一行末尾只留 1–3 个词代码块、表格和长链接目标可以超出该目标Allowed。值得注意的是docs.md 中 NautilusTrader 的源码注释规范要求行宽低于 100 字符而 Markdown 散文的行宽目标稍宽100–120两者适用对象不同不应混淆。列表破折号与全部写 1.无序列表项统一使用-对应MD004的dash风格NautilusTrader 的编码规范同样在 Rust/Python/Shell 注释中坚持用-而非*仅当顺序有意义时才使用有序列表Transitional 规则有序列表的每个源行都写1.由渲染器自动编号对应MD029的行为但该规则当前仍被禁用见下文过渡性采用列表的缩进与间距与本地 markdownlint 配置保持一致MD007配置为 2 空格缩进、首层不缩进、MD030配置列表标记后 1 空格列表前后各留一个空行对应MD032。示例规范原文- First item - Second item 1. First step 1. Second stepAdmonitions提示块GitHub Alert 与可移植回退Admonition 的使用必须遵循只使用仓库有文档说明且能渲染的语法这一总原则具体分三种情形仓库文档化并支持 GitHub Alerts 时使用 GitHub blockquote alert 形式类型限定为NOTE、TIP、IMPORTANT、WARNING、CAUTION之一该扩展不存在或未确认支持时使用可移植的 blockquote 粗体文本标签形式多段落 admonition每个内容行和空行续行都要以开头一个裸空行即结束该 admonition。规范还强调两点类型标签必须在源码和渲染输出中都保留不能只靠颜色或图标传达含义在窄幅编辑中要保留已确立且受支持的既有 admonition 语法不要仅为套用回退形式而转换它。 [!WARNING] Back up the database before running the migration.可移植回退形式 **Warning:** Back up the database before running the migration.需要注意NautilusTrader 的文档站fumadocs见 docs.md在 MDX 环境中使用的是:::note、:::info、:::tip、:::warning、:::danger这组 admonition 语法并警告过度使用 admonition 会削弱其影响力。这两套语法服务于不同场景——markdown_style.md是面向所有采用该基线的仓库的可移植基准而 docs.md 的 MDX admonition 是本地文档站的既定扩展写作时需根据目标文件所在的渲染环境选择正确的形式。表格GFM 管道表格与对齐规范表格是 NautilusTrader 文档中出现频率最高的元素之一能力矩阵、支持表、参数表规范与工具对它的约束也最细使用 GFM 管道表格包含首尾竖线对应MD055的leading_and_trailing风格竖线垂直对齐每列填充到最宽单元格宽度 两侧各一空格与 Prettier 的默认表格输出一致。MD060只检查竖线对齐、不检查单元格内容宽度因此列可以比内容更宽分隔行单元格两侧也要填充空格| ----- |而不是|-----|MD060同样不检查此项文本列默认左对齐数字列按需右对齐分隔行右侧冒号----:表示右对齐分隔行与预期的渲染对齐方式保持一致避免使用 HTML 表格除非 Markdown 无法表达所需结构或仓库有文档说明。规范原文示例| Name | Value | | ----- | ----: | | Alpha | 42 | | Beta | 17 |表格的自动化规整scripts/check-markdown-tables.py 提供了比 markdownlint 更进一步的保障它的实现细节印证了规范中的陈述使用正则DELIMITER_RE识别分隔行并用围栏检测FENCE_RE跳过代码块内的表格按列宽计算时使用utf16_width对 BMP 之外的字符如✓按宽度 2 计数确保✓、-这类支持矩阵符号不会破坏对齐cell_alignment根据单元格两侧空格数推断左/右/居中对齐分隔行冒号位置决定渲染对齐规整结果为最宽单元格 2的列宽、MIN_DASHES 3的最小分隔线长度与规范每列填充到最宽单元格加一空格完全对应脚本发现需要规整的文件时返回退出码 1从而让check-markdown目标失败并提示normalized table column widths。docs.md 还补充了支持矩阵的语义约定用✓表示支持、用-表示不支持而非✗不支持的说明用斜体*Not supported*强调并按原因细化——*Not supported by venue*表示交易所能力缺口、*Not currently implemented*表示适配器尚未实现。代码围栏、语言标注与行内代码使用反引号围栏代码块不用缩进代码块对应MD046的fenced风格MD048规定围栏符号为反引号Transitional 规则每个开围栏都必须标注语言无更具体语法的纯文本或输出使用text当文档本身要展示带围栏的 Markdown 时使用更长的外层围栏例如四反引号包三反引号命令、文件名、函数、类型、环境变量、配置键和标识符使用行内代码。嵌套围栏示例rust fn main() { println!(Hello); }docs.md 对代码引用还有一条实用约定引用代码位置时使用 file_path::function_name 或 file_path::ClassName 形式而**不用行号**——行号会随代码变更而过时。这与本文章前面引用 Makefile 目标、脚本函数的方式一致。 ## 强调、分隔线与链接图片 - 强调用 *italic*强强调用 **bold**对应 MD049/MD050 的 asterisk 风格 - 避免无意义的强调 - 分隔线使用三个连字符 ---对应 MD035 的 hr-style - 链接使用描述性文本对应 MD059例如用账户配置文档而非点击这里 - 优先行内链接同一目标在文档中出现多次时优先引用式链接对应 MD052/MD053 对引用定义的要求 - 避免裸 URL对应 MD034 - 渲染器支持时保持内部链接为相对路径 - 图片必须有有用的替代文本alt text纯装饰图片才允许使用空 alt对应 MD045。 ## HTML优先可移植 Markdown - 优先使用可移植的 Markdown 语法而非原始 HTML - 仅当 Markdown 无法表达所需结果、或仓库有文档说明该元素/组件时才使用原始 HTML - 在编辑周边内容时保留受支持的 front matter、MDX 组件、围栏属性和其他仓库扩展这些在 NautilusTrader 的 fumadocs 文档站中广泛存在例如 docs.md 记录的 Tabs、Steps、Accordions、Files、Cards、TypeTable 组件。 ## 文件级别要求编码、换行与空白 - 使用 **UTF-8** 编码 - 使用 **LF** 行尾对应 check-markdown-tables.py 写入时显式指定 newline\n - 文件以**一个换行符结尾**对应 MD047 - 不遗留行尾空格也不使用尾随空格制造 Markdown 硬换行对应 MD009 的 br_spaces: 0。 ## 编辑指引窄幅修改与结构重构的不同策略 规范针对创建或修改 Markdown给出了场景化的操作建议 - **窄幅修改narrow edits**保留周边风格直接用 markdownlint 检查即可不必通读整份指南——除非两者都留下具体未决问题 - **创建或大幅重构文档之前**只查阅仓库本地 Markdown 指南的相关章节对 NautilusTrader 而言是 docs.md 与 markdown_style.md 的对应小节 - **保留既有文档结构**除非任务本身要求变更 - 格式与周边内容和受支持的渲染器扩展保持一致 - **不要重排无关章节** - 可用时运行仓库的聚焦 Markdown 检查即 make check-markdown。 这套指引同样适用于 AI 辅助写作场景小范围修订交给 linter 把关大范围创作先对齐本地风格指南始终把变更面控制在任务范围内。 ## 过渡性采用Transitional adoption规则与迁移的平衡 规范最后说明了哪些规则立即生效、哪些处于过渡状态 - **ATX 标题通过 MD003 立即强制执行**非过渡 - **重复的 1. 有序列表标记**和**开围栏语言标注**是过渡性规则——它们对应的 MD029有序列表前缀与 MD040围栏代码语言**在既有文档完成单独机械迁移之前保持禁用** - 因此不要为了迁移那些既有构造而扩大一次窄幅文档修改的范围。 这一设计与 .markdownlint.jsonc 的配置完全吻合MD003 处于开启状态而 MD029、MD040 未出现在启用清单中。它体现了规范制定的核心理念——**风格演进应当是新增内容先守新规、存量内容分批迁移而不是一次性大规模重写**既保证了向前的一致性又避免了对既有文档的破坏性变更。 ## 小结一条从规范到工具的完整链路 NautilusTrader 的 Markdown 风格管理是一套自洽的工程体系 1. **意图层**[docs/developer_guide/markdown_style.md](https://link.gitcode.com/i/a180ffb7d2b019812178e043c6647c7e) 定义共享基线规则层级、语法选择、元素写法 2. **本地化层**[docs/developer_guide/docs.md](https://link.gitcode.com/i/f36463b1018f39ae057e7dcf0922efac) 定义 NautilusTrader 文档特有约定文档类型、语气、MDX 组件、支持矩阵 3. **机械层**[.markdownlint.jsonc](https://link.gitcode.com/i/b539fbf43efe8d3462c23ed78c64cfe0) 以默认关闭 显式启用方式固化规则子集 4. **执行层**[Makefile](https://link.gitcode.com/i/fe64e26fff4e32bdd7e81cef055be655#L654-L658) 的 check-markdown 串联 markdownlint-cli2 与 [scripts/check-markdown-tables.py](https://link.gitcode.com/i/a2b7cbe199552f293ee9a5e65e9b8769)配合 pre-commit 钩子实现提交前自动规整。 对贡献者而言日常写作只需遵循两条主线**新增内容按规范书写过渡规则对新内容立即生效****提交前运行 make check-markdown 并通过**。把握住共享基线 本地指南 自动化强制的分层思想就能在保持文档风格统一的同时让每一次文档变更都可验证、可追踪。【免费下载链接】nautilus_traderProduction-grade Rust-native trading engine with deterministic event-driven architecture项目地址: https://gitcode.com/GitHub_Trending/na/nautilus_trader创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考