Doorstop 是一款基于版本控制的需求管理工具，把需求条目以文本文件的形式存进 Git 等仓库，让需求变更像代码一样可追踪。想真正用好它，关键就在每个需求文档目录下的.doorstop.yml配置文件——它决定了需求如何编号、如何校验、以什么格式发布。本文带你完整掌握 Doorstop 进阶配置：从 settings 五大参数到 Markdown 格式需求写法，再配合!include、模板与扩展钩子，6 个实用玩法让需求管理工作流效率翻倍。

一、.doorstop.yml 是什么：需求文档的"大脑"

在 Doorstop 中，每个需求文档就是一个文件夹，文件夹根部的.doorstop.yml是该文档的元数据与配置中心，完整的树状结构定义见 docs/reference/tree.md。执行doorstop create REQ ./reqs创建文档后，Doorstop 会自动生成一份默认配置：

settings: digits: 3 prefix: REQ itemformat: yaml sep: ''

项目自带的示例配置可以直接参考：reqs/.doorstop.yml、reqs/tutorial/.doorstop.yml。官方参数详解见 docs/reference/document.md。

二、settings 五大参数：决定需求 UID 如何生成

💡实用技巧：创建时用-s -指定分隔符，UID 会更易读：

doorstop create -s - REQ ./reqs # 生成的条目为 REQ-001

其中itemformat参数是通往下一节 Markdown 玩法的开关。

三、attributes 扩展属性：defaults 与 publish 两个隐藏技能

attributes段是.doorstop.yml进阶配置的重头戏，主要有两个子项：

1.defaults：新条目的默认值模板

在defaults下写的每个键值对，都会自动填充到doorstop add新建的条目里。项目示例 reqs/tutorial/.doorstop.yml 中就预置了文档标题、版本号、作者等信息，新建条目不再是空白模板：

attributes: defaults: doc: name: 'Tutorial' title: 'Tutorial for _Doorstop_ requirements management' ref: 'TUT-DS-2024' major: '1' minor: 'A'

2.publish：控制发布时展示哪些属性

默认情况下自定义属性不会出现在发布文档里。在attributes下加一个publish列表，指定要输出的属性名即可，发布后它们会以属性表格的形式渲染出来。用法示例见 docs/cli/publishing.md 与 docs/reference/item.md。

四、itemformat: markdown——用 Markdown 写需求

这是本次终极玩法的核心。把itemformat改为markdown，需求条目就变成带 YAML frontmatter 的.md文件（与 Jekyll 等工具同源的概念）：

--- active: true derived: false level: 1.2.3 links: - SYS001: null normative: true reviewed: null --- # 标题会自动写入 header 属性 正文就是 text 属性，完整支持 Markdown 语法： 表格、图片、代码块、PlantUML 图……

规则很简单：

• 第一个一级标题自动成为header属性，无需手写
• 标题之后的正文整体作为text属性
• frontmatter 中只写结构化字段，彻底告别 YAML 缩进地狱

可运行实例见 doorstop/core/tests/files_md/REQ001.md，配套配置 doorstop/core/tests/files_md/.doorstop.yml 中正是itemformat: markdown。两种格式也可以在同一棵文档树中混用，按文档粒度各自配置。

五、!include 指令：一份配置，多处复用

.doorstop.yml支持用!include标签引入外部 YAML 文件（路径相对于当前文件，不支持绝对路径）：

attributes: defaults: text: !include path/to/template.yml

典型用法是把公共模板放在共享目录（类似项目测试中的 doorstop/core/tests/files/a/template.yml 通过!include b/template.yml二次引用），所有子文档统一引用，从根源上消除复制粘贴。

六、extensions 与发布：让配置直接驱动工作流

1. 扩展钩子：extensions段可为单个文档挂载校验器。项目自带的 reqs/ext/.doorstop.yml 就启用了自定义校验脚本与引用文件 SHA-256 指纹：

extensions: item_validator: .req_sha_item_validator.py item_sha_required: true

这让不同文档拥有不同的校验规则，doorstop完整性检查时自动执行，参考 docs/api/scripting.md。

2. 模板（template）：与.doorstop.yml同级放一个template文件夹，即可定制 HTML/LaTeX 发布样式；内置模板文件在 doorstop/core/files/templates/ 目录下。

3. 资产（assets）：同级的assets文件夹会原样复制到发布输出目录，需求正文里用相对路径引用图片、PDF 即可，实现图文并茂的需求文档。

七、进阶避坑清单

• prefix、digits、parent创建后视同只读，改前缀等于重建文档
• sep必须在创建条目之前设置，之后改动会导致 UID 混乱
• itemformat切换格式前，先确认编辑器和团队成员都熟悉 Markdown
• !include不支持绝对路径，跨目录引用请写相对路径
• 完整命令速查见 docs/getting-started/quickstart.md，进阶创建/发布/校验文档见 docs/cli/ 目录

总结：.doorstop.yml是 Doorstop 的"大脑"——settings 管编号，attributes 管默认值与输出，itemformat 管书写格式，include 与 extensions 管复用与自动化。把这五层配置玩透，你就能用纯文本 + 版本控制构建一套轻量、可追溯、图文并茂的专业需求管理体系。