开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载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()可以看到其解析规则先扫描所有声明中带有outputShortcut标记且已设置的选项html、json均在 src/lib/utils/options/sources/typedoc.ts#L283-L296 中以outputShortcut注册out是特殊分支只要options.isSet(out)就以defaultOutput插件可改写out路径组成一个输出项只要有任何快捷方式被使用outputs选项就会被整体忽略若既没有快捷方式也没有outputs则回落到默认输出类型写入out默认./docs。每份输出独立执行的逻辑在Outputs.writeOutput()src/lib/output/output.ts#L83-L131先对当前选项做快照应用该项的options覆盖调用对应 writer最后恢复选项并记录耗时。这就是为什么可以为不同输出配置不同的navigation。两种内置输出 writer 的注册在 src/lib/application.ts#L232-L240json输出通过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取值行为docs只输出文档不输出 JS默认both同时输出文档和 JSnone什么都不输出只转换并运行校验注意如果tsconfig.json中配置了declaration: trueemit: both会同时生成类型声明文件。主题与路由theme、routertheme$ 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-L176kind默认——按成员类别创建文件夹kind-dir——同 kind但每个页面渲染为目录内的index.html可获得干净 URLstructure——按模块结构创建文件夹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.htmlkinddocs ├── classes │ └── Options.html ├── functions │ └── initialize.html ├── modules │ └── TypeDoc.html └── variables └── TypeDoc.VERSION.htmlstructure├── initialize.html ├── Options.html ├── TypeDoc │ └── VERSION.html └── TypeDoc.htmlgroupdocs ├── 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-plussrc/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 会发出警告把语言名加入此列表即可消除该警告。默认值为空数组。类型排版宽度typePrintWidthtypedoc --typePrintWidth 120指定渲染类型时换行的宽度默认80src/lib/utils/options/sources/typedoc.ts#L380-L385。官方建议除非你同时调整了所用主题的样式否则不要修改此值否则类型展示可能溢出页面版式。静态资源注入与页面装饰customCss / customJs$ typedoc --customCss ./theme/style.css $ typedoc --customJs ./theme/custom.jscustomCss指定额外 CSS 文件会被复制到输出的assets目录并由主题引用customJs指定一个 JavaScript脚本非模块文件同样复制到assets目录并由主题引用适合注入页面行为而无需完整主题。两者均声明为ParameterType.Path即路径会被规范化处理。customFooterHtml / customFooterHtmlDisableWrapper$ typedoc --customFooterHtml Copyright strongProject/strong 2024 $ typedoc --customFooterHtml pCopyright strongProject/strong 2024/p --customFooterHtmlDisableWrappercustomFooterHtml指定注入到页面页脚的额外 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指定的输出目录默认truesrc/lib/utils/options/sources/typedoc.ts#L554-L559。设为false可保留目录中的旧文件适合增量式部署场景。页头与侧边栏链接navigationLinks、sidebarLinks// typedoc.json { navigationLinks: { Example: http://example.com } }在页头加入额外链接键为链接文本、值为 URL。sidebarLinks同理但链接显示在页面侧边栏中。两者源码校验规则一致值必须是对象且所有键的取值都是字符串 URLsrc/lib/utils/options/sources/typedoc.ts#L565-L602。Markdown 解析markdownItOptions 与 markdownItLoaderTypeDoc 使用 markdown-it 解析文档注释中的 Markdown 内容对应两个选项markdownItOptions{ markdownItOptions: { html: true, linkify: true } }这些选项会原样转发给 markdown-it 解析器。TypeDoc 的默认覆盖值就是上面这两个html: true允许注释中出现原始 HTMLlinkify: 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 会取所有源文件的最低公共目录来猜测。上例中若未指定displayBasePathTypeDoc 显示的路径将是index.ts而非src/index.ts。未设置时默认取 basePath 的值。注意此选项只影响显示出来的路径不影响 TypeDoc 生成链接的目标位置。lang / locales$ typedoc --lang zhlang同时决定 HTML 输出的html lang...属性与生成文档时使用的翻译文案默认en即html langen。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、生成 canonicallink标签以及支撑下面这个选项。源码校验要求该值必须以http(s)://开头src/lib/utils/options/sources/typedoc.ts#L510-L518。useHostedBaseUrlForAbsoluteLinks设为true时TypeDoc 会生成指向各页面的绝对链接而非相对链接默认false。sourceLinkExternal / markdownLinkExternal$ typedoc --sourceLinkExternal $ typedoc --markdownLinkExternalsourceLinkExternal生成 HTML 时把源码链接视为外部链接在新标签页打开markdownLinkExternal让注释和 Markdown 文件中的http[s]://链接被视为外部链接并在新标签页打开。注意源码中该选项默认值已是truesrc/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、visibilityFiltersnavigation// 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: falsesrc/lib/utils/options/sources/typedoc.ts#L608-L619。几个行为细节categorizeByGroup 选项也会影响此行为。若该选项为开默认且includeGroups未设置则类别只会在分组内部创建includeCategories的效果实际上被忽略项目文件夹是否变成导航栏中的嵌套下拉框由navigation.includeFolders决定默认true且仅在项目包含位于不同文件夹的多个入口点时才有意义。includeCategories/includeGroups还可以在注释级别用标签按反射覆盖showGroups/hideGroupsshowCategories/hideCategoriesnavigationLeaves// 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: falsesrc/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此选项决定是用注释的第一段作为短摘要还是留空。includeHierarchySummarytypedoc --includeHierarchySummary false控制是否在输出中生成hierarchy.html页面列出全部成员的完整类层级默认truesrc/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等命令行只传路径类快捷方式以获得最可控的多格式文档流水线。赞分享开发工具文档【免费下载链接】typedocDocumentation generator for TypeScript projects.项目地址https://gitcode.com/gh_mirrors/ty/typedoc点击查看免费下载相关推荐RomM导出格式定制CSV、JSON与PDF输出选项RomM导出格式定制CSV、JSON与PDF输出选项 在游戏收藏管理中数据的灵活导出是满足个性化需求的关键功能。RomM作为一款强大的自托管ROM管理器提后端前端TypeDoc 配置系统实战配置文件、输入输出、注释解析与校验选项全解TypeDoc 配置系统实战配置文件、输入输出、注释解析与校验选项全解 TypeDoc 的所有行为——读哪些文件、怎么解析注释、生成什么输出、如何校验文档完整开发工具文档SQLite 向量扩展加载失败三步定位并修复 macOS 上的 dylib 问题SQLite 向量扩展加载失败三步定位并修复 macOS 上的 dylib 问题 sqlite vec 是一个可嵌入任意 SQLite 的向量搜索扩展但不少向量数据库数据库上一篇大模型部署全攻略Qwen3-VL-4B-Instruct选型与性能优化指南下一篇Scrapy-Cluster实战教程从配置到部署的完整路线图创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
