TypeDoc 输出选项全解：配置 html、json 与多输出、路由与站点定制

• 开发工具
• 文档

TypeDoc 在将 TypeScript 项目转换为文档模型之后，需要通过一组"输出类"选项决定文档写到哪里、以什么格式写出，以及生成的 HTML 站点如何组织目录、定制外观与搜索行为。本文完整覆盖 TypeDoc 官方文档中 Output 分类下的全部配置项（outputs、out、emit、router、高亮主题、navigation等），并结合当前仓库源码说明各选项的默认值、取值校验与底层执行流程，帮助你在一次构建中同时产出 HTML、JSON、Markdown 等多种格式，并按需定制站点结构。

多格式同时输出：outputs 与输出快捷方式

TypeDoc 支持在一次运行中渲染多种输出。outputs选项是一个数组，每一项指定输出类型名称、写入路径，以及该份输出独有的选项覆盖：

// typedoc.json { "outputs": [ { "name": "html", "path": "./docs_html" }, { "name": "html", "path": "./docs_html_full_nav", "options": { "navigation": { "includeCategories": true, "includeGroups": true, "excludeReferences": false, "includeFolders": true } } }, { "name": "json", "path": "./docs.json" }, { // 需要 typedoc-plugin-markdown 插件 "name": "markdown", "path": "./docs_markdown" } ] }

TypeDoc 内置的输出类型是html与json；插件（如 markdown 插件）可注册新的输出类型。options键中可以写入任意选项，但要注意：只有在输出阶段（而非转换阶段）生效的选项，才会对该份输出产生影响。

输出快捷方式：out、html、json

除outputs外，还有三个单格式快捷方式：

$ typedoc --out <path/to/documentation/> $ typedoc --html <path/to/documentation/> $ typedoc --json <path/to/out-file.json>

• --out指定默认输出类型的写入位置。默认情况下即生成 HTML，但如果加载了会修改默认输出类型的插件，--out指向的就是该插件定义的输出；
• --html直接指定 HTML 文档的输出目录；
• --json指定包含全部反射数据（reflection data）的 JSON 文件路径，可用于驱动第三方文档生成器或作为下游工具的数据源。

三者的共同点是：它们都是输出快捷方式。从源码 src/lib/output/output.ts#L30-L73 中的Outputs.getOutputSpecs()可以看到其解析规则：

1. 先扫描所有声明中带有outputShortcut标记且已设置的选项（html、json均在 src/lib/utils/options/sources/typedoc.ts#L283-L296 中以outputShortcut注册）；
2. out是特殊分支：只要options.isSet("out")，就以defaultOutput（插件可改写）+out路径组成一个输出项；
3. 只要有任何快捷方式被使用，outputs选项就会被整体忽略；
4. 若既没有快捷方式也没有outputs，则回落到默认输出类型写入out（默认./docs）。

每份输出独立执行的逻辑在Outputs.writeOutput()（src/lib/output/output.ts#L83-L131）：先对当前选项做快照，应用该项的options覆盖，调用对应 writer，最后恢复选项并记录耗时。这就是为什么可以为不同输出配置不同的navigation。

两种内置输出 writer 的注册在 src/lib/application.ts#L232-L240：json输出通过serializer.projectToObject()序列化后用JSON.stringify写出；html输出则委托给Renderer.render()。

JSON 输出的格式化与 emit 策略

pretty

$ typedoc --json out.json --pretty

控制 JSON 输出是否美化格式，默认true（见 src/lib/utils/options/sources/typedoc.ts#L297-L302）。从jsonwriter 实现看，pretty为true时使用制表符缩进，否则输出紧凑单行。

emit

$ typedoc --emit none

指示 TypeDoc 像tsc一样写出编译产物。取值为EmitStrategy枚举（定义于 src/lib/utils/options/declaration.ts#L22-L28），默认docs：

注意：如果tsconfig.json中配置了declaration: true，emit: both会同时生成类型声明文件。

主题与路由：theme、router

theme

$ typedoc --theme default

指定渲染 HTML 使用的主题名称。默认值为default。从 src/lib/output/renderer.ts#L176-L178 的themes映射表看，内置主题目前只有default一个，其余主题需由插件/主题包注册。

router

$ typedoc --router default

指定决定"HTML 输出中创建哪些页面、页面之间如何相互链接"的路由器。插件/主题可以注册额外路由。TypeDoc 内置六种路由（注册于 src/lib/output/renderer.ts#L169-L176）：

• kind（默认）——按成员类别创建文件夹；
• kind-dir——同 kind，但每个页面渲染为目录内的index.html，可获得"干净" URL；
• structure——按模块结构创建文件夹；
• structure-dir——同 structure，但使用目录 +index.html形式；
• group——按反射的@group标签创建文件夹；
• category——按反射的@category标签创建文件夹。

用下面这个 API 例子最直观：

export function initialize(): void; /** @group Opts */ export class Options {} export namespace TypeDoc { export const VERSION: string; }

不同路由器产出的目录结构（省略了公共的assets文件夹与index.html/modules.html）：

kind

docs ├── classes │ └── Options.html ├── functions │ └── initialize.html ├── modules │ └── TypeDoc.html └── variables └── TypeDoc.VERSION.html

structure

├── initialize.html ├── Options.html ├── TypeDoc │ └── VERSION.html └── TypeDoc.html

group

docs ├── Opts │ └── Options.html ├── Functions │ └── initialize.html ├── Namespaces │ └── TypeDoc.html └── Variables └── TypeDoc.VERSION.html

从源码结构看，四个路由类（KindRouter、StructureRouter、GroupRouter、CategoryRouter，见 src/lib/output/router.ts#L452 起）均继承自BaseRouter，其中KindRouter维护了一张ReflectionKind到目录名的映射表（Class →classes、Interface →interfaces等），而group/category路由则读取注释中的@group/@category值作为目录名。路由器的完整契约（buildPages、relativeUrl、getFullUrl、getSlugger等）定义在 src/lib/output/router.ts#L57-L116 的Router接口中，前端搜索、层级图与导航组件都通过这些方法动态构造 URL。

代码高亮：Shiki 主题、语言列表与忽略列表

TypeDoc 使用 Shiki 对文档注释与 Markdown 中的代码块做语法高亮，涉及四个选项：

lightHighlightTheme / darkHighlightTheme

$ typedoc --lightHighlightTheme light-plus $ typedoc --darkHighlightTheme dark-plus

分别指定浅色模式与深色模式下高亮代码片段所用的 Shiki 主题。默认值分别为light-plus与dark-plus（src/lib/utils/options/sources/typedoc.ts#L323-L324）。选项声明中带有校验：取值必须是 Shiki 内置（bundled）主题之一，否则报错并列出全部合法主题名。

highlightLanguages

指定要加载的 Shiki 语法（grammar）。官方文档给出的默认列表如下：

{ "highlightLanguages": [ "bash", "console", "css", "html", "javascript", "json", "jsonc", "json5", "tsx", "typescript" ] }

补充一点仓库现状：当前源码中该默认列表（src/lib/utils/options/defaults.ts#L72-L84）还额外包含yaml。选项声明处同样带校验——数组中出现 Shiki 不支持的语言会直接报错（highlightLanguages_contains_invalid_languages_0）。

ignoredHighlightLanguages

{ "ignoredHighlightLanguages": ["mkdocs"] }

指定代码块中使用的哪些语言应被 TypeDoc静默忽略。默认行为是：如果某个代码块声明的语言不在highlightLanguages中，TypeDoc 会发出警告；把语言名加入此列表即可消除该警告。默认值为空数组。

类型排版宽度：typePrintWidth

typedoc --typePrintWidth 120

指定渲染类型时换行的宽度，默认80（src/lib/utils/options/sources/typedoc.ts#L380-L385）。官方建议：除非你同时调整了所用主题的样式，否则不要修改此值，否则类型展示可能溢出页面版式。

静态资源注入与页面装饰

customCss / customJs

$ typedoc --customCss ./theme/style.css $ typedoc --customJs ./theme/custom.js

• customCss：指定额外 CSS 文件，会被复制到输出的assets目录并由主题引用；
• customJs：指定一个 JavaScript脚本（非模块）文件，同样复制到assets目录并由主题引用，适合注入页面行为而无需完整主题。

两者均声明为ParameterType.Path，即路径会被规范化处理。

customFooterHtml / customFooterHtmlDisableWrapper

$ typedoc --customFooterHtml "Copyright <strong>Project</strong> 2024" $ typedoc --customFooterHtml "<p>Copyright <strong>Project</strong> 2024</p>" --customFooterHtmlDisableWrapper

customFooterHtml指定注入到页面页脚的额外 HTML 片段。默认情况下，TypeDoc 会把该片段包裹在一个<p>元素中，以便纯文本也能对齐显示；customFooterHtmlDisableWrapper用于关闭这一包裹行为（当你自己已经写好了块级元素时）。

favicon

$ typedoc --favicon favicon.ico

指定站点 favicon。源码中的校验逻辑（src/lib/utils/options/sources/typedoc.ts#L475-L492）要求：取值必须是http(s)://URL，或扩展名为.ico/.png/.svg的文件路径，否则抛出校验错误。

cname

$ typedoc --cname typedoc.org

在输出目录中创建一个内容为指定文本的CNAME文件，用于将文档站点绑定到自定义域名（常见于 GitHub Pages 子目录站点）。

cacheBust

$ typedoc --cacheBust

启用后，TypeDoc 会在引用 JS/CSS 资源的<script>和<link>标签中加入生成时间戳，防止浏览器使用上一次构建的旧资源。配置得当的 Web 服务器一般不需要此选项。

hideGenerator

$ typedoc --hideGenerator

不在页面底部打印 TypeDoc 链接，默认false（即默认显示）。

titleLink

$ typedoc --titleLink "http://example.com"

设置页头标题链接的指向，默认为文档首页。

cleanOutputDir

$ typedoc --cleanOutputDir false

控制 TypeDoc 是否清理--out指定的输出目录，默认true（src/lib/utils/options/sources/typedoc.ts#L554-L559）。设为false可保留目录中的旧文件，适合增量式部署场景。

页头与侧边栏链接：navigationLinks、sidebarLinks

// typedoc.json { "navigationLinks": { "Example": "http://example.com" } }

在页头加入额外链接，键为链接文本、值为 URL。sidebarLinks同理，但链接显示在页面侧边栏中。两者源码校验规则一致：值必须是对象且所有键的取值都是字符串 URL（src/lib/utils/options/sources/typedoc.ts#L565-L602）。

Markdown 解析：markdownItOptions 与 markdownItLoader

TypeDoc 使用 markdown-it 解析文档注释中的 Markdown 内容，对应两个选项：

markdownItOptions

{ "markdownItOptions": { "html": true, "linkify": true } }

这些选项会原样转发给 markdown-it 解析器。TypeDoc 的默认覆盖值就是上面这两个：html: true允许注释中出现原始 HTML，linkify: true让裸 URL 自动成为链接。该选项声明为configFileOnly: true，即只能在配置文件（JSON/JS 配置）中设置，不能通过命令行传入，默认值定义在 src/lib/utils/options/sources/typedoc.ts#L397-L413。

markdownItLoader

一个函数选项，只能在 JS 配置文件中设置，用于给 markdown-it 实例挂载插件。它会被传入一个MarkdownIt实例调用：

// typedoc.config.mjs export default { markdownItLoader(parser) { parser.use(plugin1); }, };

源码中的校验要求该选项必须是函数类型（默认值为空函数）。同样为configFileOnly选项。

路径与国际化显示

displayBasePath

$ typedoc --displayBasePath ./ --entryPoints src/index.ts

指定显示文件路径时使用的基准路径。若不设置，TypeDoc 会取所有源文件的最低公共目录来猜测。上例中若未指定displayBasePath，TypeDoc 显示的路径将是index.ts而非src/index.ts。未设置时默认取 basePath 的值。

注意：此选项只影响显示出来的路径，不影响 TypeDoc 生成链接的目标位置。

lang / locales

$ typedoc --lang zh

lang同时决定 HTML 输出的<html lang="...">属性与生成文档时使用的翻译文案，默认en（即<html lang="en">）。

locales用于提供自定义翻译，作用于--lang指定的语言：

// typedoc.json { "locales": { "zh": { "flag_private": "私有" } } }

所有可翻译文案的键名列表见 src/lib/internationalization/translatable.ts。locales的源码校验（src/lib/utils/options/sources/typedoc.ts#L58-L81）要求它是一个两层嵌套对象，且叶子值必须是字符串。如果你的翻译对社区有通用价值，可以考虑向 TypeDoc 提交合并请求。

部署相关：githubPages、hostedBaseUrl、外链处理

githubPages

$ typedoc --githubPages false

默认true。启用时，TypeDoc 会在输出目录中写入.nojekyll文件，防止 GitHub Pages 用 Jekyll 处理你的文档站点——当你有 scoped packages 时，TypeDoc 会生成以_开头的 HTML 文件，而 Jekyll 会忽略这些文件。

hostedBaseUrl / useHostedBaseUrlForAbsoluteLinks

// typedoc.json { "hostedBaseUrl": "https://example.com", "useHostedBaseUrlForAbsoluteLinks": true }

hostedBaseUrl指定文档站点的托管基础 URL，用于生成 sitemap、生成 canonical<link>标签，以及支撑下面这个选项。源码校验要求该值必须以http(s)://开头（src/lib/utils/options/sources/typedoc.ts#L510-L518）。

useHostedBaseUrlForAbsoluteLinks设为true时，TypeDoc 会生成指向各页面的绝对链接而非相对链接，默认false。

sourceLinkExternal / markdownLinkExternal

$ typedoc --sourceLinkExternal $ typedoc --markdownLinkExternal

• sourceLinkExternal：生成 HTML 时把源码链接视为外部链接，在新标签页打开；
• markdownLinkExternal：让注释和 Markdown 文件中的http[s]://链接被视为外部链接并在新标签页打开。注意源码中该选项默认值已是true（src/lib/utils/options/sources/typedoc.ts#L498-L503）。

搜索定制：范围与相关性加权

searchInComments / searchInDocuments

$ typedoc --searchInComments $ typedoc --searchInDocuments

分别启用"在注释文本中搜索"和"在文档（document）文本中搜索"。两者默认关闭。

注意：启用任一选项都会增大搜索索引体积；在注释/文档很多且偏长的大型项目中，索引可能增大近一个数量级。

searchCategoryBoosts / searchGroupBoosts

// typedoc.json { "searchCategoryBoosts": { "Common Items": 1.5 }, "searchGroupBoosts": { "Classes": 1.5 } }

分别对类别（category）和分组（group）内的搜索结果提升相关性权重。两者源码声明均为configFileOnly，且校验所有取值必须是数字（src/lib/utils/options/sources/typedoc.ts#L680-L721），便于让常用模块在搜索中优先显示。

导航树构建：navigation、navigationLeaves、visibilityFilters

navigation

// typedoc.json { "navigation": { "includeCategories": true, "includeGroups": false, "includeFolders": true, "compactFolders": false, "excludeReferences": true }, "categorizeByGroup": false }

决定左侧导航的构建方式。源码中该选项是 Flags 类型，各子项默认值为includeCategories: false、includeGroups: false、includeFolders: true、compactFolders: true、excludeReferences: false（src/lib/utils/options/sources/typedoc.ts#L608-L619）。

几个行为细节：

• categorizeByGroup 选项也会影响此行为。若该选项为开（默认）且includeGroups未设置，则类别只会在分组内部创建，includeCategories的效果实际上被忽略；
• 项目"文件夹"是否变成导航栏中的嵌套下拉框，由navigation.includeFolders决定（默认true），且仅在项目包含位于不同文件夹的多个入口点时才有意义。

includeCategories/includeGroups还可以在注释级别用标签按反射覆盖：

• @showGroups/@hideGroups
• @showCategories/@hideCategories

navigationLeaves

// typedoc.json { "navigationLeaves": ["JSONOutput"] }

指定导航树中不可展开的命名空间/模块。指定嵌套命名空间时，按显示树用.分隔各级父名，并跳过顶层项目链接，例如ParentNS.ChildNS。

visibilityFilters

// typedoc.json { "visibilityFilters": { "protected": false, "private": false, "inherited": true, "external": false, "@alpha": false, "@beta": false } }

指定浏览页面时可用哪些过滤器。protected、private、inherited、external四个内置过滤器默认全部显示；把某个键的默认值改掉，或直接从该选项中省略某个键，即可调整或禁用对应过滤器。此外还可以指定修饰标签（modifier tag，如@alpha）引入基于标签的自定义过滤。

源码校验（src/lib/utils/options/sources/typedoc.ts#L645-L678）确认了规则：允许的键要么是四个内置键，要么以@开头（视为标签名），且所有取值必须是布尔值，否则报错。

页面标题、锚点与成员摘要

headings

// typedoc.json { "headings": { "readme": true, "document": false } }

控制渲染页面是否包含描述该反射的标题。源码默认值即readme: true、document: false（src/lib/utils/options/sources/typedoc.ts#L620-L628）：读取 README 生成的首页默认显示标题，而通过@document引入的外部文档默认不显示。

sluggerConfiguration

// typedoc.json { "sluggerConfiguration": { "lowercase": true } }

决定页面内锚点（anchor）的生成方式，主要是向后兼容选项，未来版本可能移除。背景是 TypeDoc 0.26 不对页内标题做小写化，这与 GitHub Pages 站点常见的标题锚点规则不一致，也不利于 VSCode 在外部 Markdown 文件中自动补全锚点；从 0.27 起默认lowercase: true。

useFirstParagraphOfCommentAsSummary

// typedoc.json { "useFirstParagraphOfCommentAsSummary": true }

渲染模块或命名空间页面时，TypeDoc 会为每个"渲染在其他页面上"的成员显示一条"短摘要"。若使用了@summary标签，则以其文本为准；若未使用@summary，此选项决定是用注释的第一段作为短摘要，还是留空。

includeHierarchySummary

typedoc --includeHierarchySummary false

控制是否在输出中生成hierarchy.html页面（列出全部成员的完整类层级），默认true（src/lib/utils/options/sources/typedoc.ts#L638-L643）。层级页面由输出管线中的 HierarchyPlugin 生成（见 src/lib/output/plugins/HierarchyPlugin.ts）。

小结

TypeDoc 的输出选项围绕三条主线组织：输出目标（outputs/out/html/json/pretty，多格式并行产出且支持逐项选项覆盖）、站点结构（theme、router六种路由、navigation系列、sluggerConfiguration等）以及站点外观与行为（Shiki 高亮主题与语言、customCss/customJs/页脚注入、搜索范围与加权、国际化与部署选项如githubPages、hostedBaseUrl、cname）。所有默认值与校验规则均可在 src/lib/utils/options/sources/typedoc.ts 中逐项核对，输出调度与选项快照恢复的实现则在 src/lib/output/output.ts。配置时建议以typedoc.json集中管理configFileOnly选项（outputs、locales、markdownItLoader等），命令行只传路径类快捷方式，以获得最可控的多格式文档流水线。

• 开发工具
• 文档