如何将Typedoc文档自动上传至Confluence？最佳方案探讨

针对Typedoc无法生成Sphinx所需RST文件的问题，直接通过以下两种方案实现Typedoc文档到Confluence的自动化上传：

方案一：使用Typedoc专用插件（快速实现） #

该方案借助typedoc-plugin-confluence插件，直接生成Confluence兼容内容并完成上传，无需额外格式转换。

1. 安装依赖

npm install typedoc typedoc-plugin-confluence --save-dev

2. 配置Typedoc
   在项目根目录创建typedoc.json，填入Confluence实例信息和文档配置：

{
  "entryPoints": ["./src/index.ts"], // 你的TS入口文件路径
  "plugin": ["typedoc-plugin-confluence"],
  "confluence": {
    "baseUrl": "https://你的Confluence实例地址",
    "username": "你的Confluence登录邮箱",
    "apiToken": "你的Atlassian API Token",
    "spaceKey": "目标空间的Key",
    "parentPageId": "可选：父页面ID，用于将文档放在指定页面下",
    "title": "TypeScript API 文档" // 上传后Confluence页面的标题
  }
}

3. 执行生成与上传
   直接运行Typedoc命令即可完成全流程：

npx typedoc

方案二：自定义转换+API上传（灵活可控） #

如果插件无法满足定制需求，可通过手动转换HTML内容，再调用Confluence API完成上传，适配更复杂的文档结构。

1. 生成Typedoc HTML文档
   先通过Typedoc生成标准HTML输出：

npx typedoc --out ./docs/typedoc ./src/index.ts

2. 安装依赖工具
   安装Confluence API客户端和HTML转Confluence Wiki格式的工具：

npm install confluence-api html-to-confluence-wiki --save-dev

3. 编写上传脚本
   在项目中创建upload-confluence-docs.js脚本，实现内容转换与上传逻辑：

const Confluence = require('confluence-api');
const fs = require('fs');
const htmlToWiki = require('html-to-confluence-wiki');

// 初始化Confluence客户端
const confluence = new Confluence({
  username: '你的登录邮箱',
  password: '你的Atlassian API Token',
  baseUrl: 'https://你的Confluence实例地址'
});

// 读取并转换Typedoc生成的HTML
const htmlContent = fs.readFileSync('./docs/typedoc/index.html', 'utf8');
const wikiContent = htmlToWiki(htmlContent);

// 创建或更新Confluence页面
confluence.createOrUpdatePage(
  '目标空间Key',
  'TypeScript API 文档',
  wikiContent,
  {
    parentId: '可选：父页面ID',
    version: { number: 1, message: '首次上传文档' }
  }
).then(res => console.log('文档上传成功:', res))
.catch(err => console.error('上传失败:', err));

4. 执行上传
   运行脚本完成文档上传：

node upload-confluence-docs.js

自动化集成 #

将上述命令添加到package.json的scripts字段，或集成到CI/CD流程（如GitHub Actions、GitLab CI），实现代码提交后自动触发文档生成与上传：

{
  "scripts": {
    "docs:confluence": "npx typedoc" // 对应方案一，方案二则替换为node upload-confluence-docs.js
  }
}

注意事项 #

• Atlassian API Token需在账号设置的「API tokens」页面生成，不可使用登录密码
• 确保Confluence空间Key、页面ID等参数准确，否则会导致上传失败
• 若Typedoc生成的HTML结构复杂，转换后的Wiki内容可能需要微调，可通过自定义Typedoc主题简化输出

内容的提问来源于stack exchange，提问作者Nadib Hussain