Highlight
DocC 的 Documentation Catalog 支持文章（Articles）和扩展文件（Extensions），用 Topics 组织 API 导航，让框架文档从自动生成的列表变成有故事的结构化内容。
核心内容
你的框架有 50 个公开 API。DocC 默认按字母顺序排列，用户看到一个长长的列表，不知道从哪里开始。你需要一种方式组织这些 API，告诉用户 “先学这个，再学那个”。
DocC 的文章和扩展文件机制就是解决这个问题的。
详细内容
Documentation Catalog
（03:59）
Documentation Catalog 是一个特殊的目录，包含所有文档文件：
SlothCreator.docc/
SlothCreator.md # 框架概述文章
GettingStarted.md # 入门教程文章
Sloth.md # 类型扩展文件
Resources/
sloth.png # 图片资源创建方式：在 Xcode 中右键 Sources 目录 → New File → Documentation Catalog。
（04:55）
关键点：
.docc后缀的目录- 包含 Markdown 文章和扩展文件
- Resources 子目录存放图片等资源
- 和源代码放在同一个 target 中
顶层文章
（05:00）
顶层文章是用户看到的第一页，需要回答 “这个框架是做什么的”。
# SlothCreator
Create and care for adorable virtual sloths.
## Overview
SlothCreator provides everything you need to research,
create, and care for sloths in your app.
## Topics
### Essentials
- ``Sloth``
- ``Habitat``
### Creating Sloths
- ``SlothGenerator``
- ``Sloth/name``（05:00）
关键点：
- 标题是框架名
- 第一段是单行摘要
- Overview 提供更多上下文
- Topics 部分组织相关符号
- 图片用
语法
Topics 组织
（09:14）
Topics 用三级标题组织符号：
## Topics
### Essentials
- ``GettingStarted``
- ``Sloth``
### Research
- ``SlothGenerator``
- ``Sloth/name``
### Care
- ``Habitat``
- ``Habitat/comfortLevel``（10:00）
关键点：
## Topics是二级标题### GroupName是三级标题，定义分组- 符号用双反引号链接
- 文章用文件名（不含扩展名）链接
- 分组按复杂度从低到高排列
扩展文件
（13:56）
扩展文件让你在不修改源代码的情况下，为类型添加 Topics 组织。
# ``SlothCreator/Sloth``
## Topics
### Creating a Sloth
- ``init(name:color:power:)``
- ``init?(from:)``
### Inspecting a Sloth
- ``name``
- ``color``
- ``power``
### Caring for a Sloth
- ``sleep(in:for:)``
- ``eat(_:quantity:)``（15:00）
关键点：
- 文件名任意，但建议和被扩展的符号同名
- 标题用
`ModuleName/SymbolName`格式 - 内容和源代码中的文档注释合并
- 适合把 Topics 组织从源代码中分离
图片资源
（05:28）
DocC 支持 Dark Mode 图片和 2x 分辨率：
sloth.png # 默认图片
sloth~dark.png # Dark Mode 版本
[email protected] # 2x 分辨率
[email protected] # Dark Mode + 2xMarkdown 中只写基础文件名：
（06:02）
关键点：
- 基础文件名不带修饰符
- DocC 自动选择正确的变体
- 建议提供 2x 分辨率
- Dark Mode 图片用
~dark后缀
核心启发
-
为框架创建顶层概述文章。回答 “这个框架是做什么的”，提供一张概览图。入口 API：Documentation Catalog + 顶层 Markdown 文件。
-
用 Topics 把 API 组织成故事线。按功能分组，从基础到进阶排列。入口 API：
## Topics+### GroupName。 -
用扩展文件分离 Topics 组织。保持源代码简洁，文档结构在单独文件中维护。入口 API：扩展文件 +
`ModuleName/SymbolName`标题。 -
提供 Dark Mode 兼容的图片。用
~dark后缀命名 Dark Mode 版本。入口 API：sloth~dark.png。 -
为复杂类型编写任务文章。教用户完成一个具体任务，而不是罗列 API。入口 API：独立 Markdown 文章。
关联 Session
- Meet DocC documentation in Xcode — DocC 基础介绍和快速开始
- Build interactive tutorials in DocC — DocC 交互式教程
- Host and automate your DocC documentation — DocC 文档托管和自动化
评论
GitHub Issues · utterances