confluence-如何通过程序在 confluence 中创建 markdown 文档

ykgarfield

2018-12-23

在 confluence 中创建 markdown 文档, 首先需要安装相关的 markdown 插件.既有免费的, 也有付费的.经过试用付费的 markdown 插件, 和免费的对比一下, 发现大部分 markdown 相关的功能都基本一致.付费的提供了一些额外的特性, 比如: 允许使用 html 标签、可选择渲染表格的样式等, 另外就是提供了一个很方便的功能就是可以直接将 markdown 文件上传为附件, 并用此插件插入附件 markdown 文档.而且渲染出来的表格样式比免费的要美观很多.免费的 markdown 插件渲染出来的表格样式实在有点不忍直视, 比较丑陋.

另外, 无论是免费的还是付费的 markdown 插件都是不支持生成目录语法.大多数平台和 markdown 编辑器可以通过扩展的 [toc] 语法来实现生成目录.在 confluence 中需要插入目录宏, 而且还是可以定义展示的层级, 这个特性还是比较有用的.

不过为了节约成本, 我们当然还是优先选择免费的.通过人工操作, 写入 markdown 文档是很简单的, 但是怎么通过程序自动的在 confluence 中创建 markdown 文档呢? 目前也没有现成的 API 可以实现.不过通过人工操作并进行抓包, 我们发现可以利用以下几个 API 来实现此功能.这里将插入目录宏(Table of Contents)的操作一起加上.

插入目录宏: 发起 /rest/tinymce/1/macro/placeholder 请求.
目录宏 draft: 发起 /rest/tinymce/1/drafts 请求.
插入 markdown 宏: 还是发起 /rest/tinymce/1/macro/placeholder 请求.
更新文档(draft status): 发起 /rest/api/content/{id}?status=draft 请求

下面具体的来说明上面的几个步骤.

插入目录宏

发起 /rest/tinymce/1/macro/placeholder 请求.请求的示例如下:

{
    "contentId":"6488066",
    "macro":{
        "name":"toc",
        "params":{
            "maxLevel":"2"
        },
        "body":""
    }
}

可以看到, contentId 也就是 page 的 ID, name 固定为 toc, maxLevel 指定了目录展示的最大层次.这里只会展示两级.

响应示例:

<img class="editor-inline-macro" src="/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0yfQ&amp;locale=zh_CN&amp;version=2" data-macro-name="toc" data-macro-parameters="maxLevel=2" data-macro-schema-version="1">

这里返回的信息需要保存下面, 后面还会使用到.

目录宏 draft

发起 /rest/tinymce/1/drafts 请求.请求示例如下:

{
    "draftId":"6488067",
    "pageId":"6488066",
    "parentPageId":"5898241",
    "type":"page",
    "title":"markdown测试",
    "spaceKey":"SPC",
    "content":"<p><img class="editor-inline-macro" src="http://localhost:8090/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0yfQ&locale=zh_CN&version=2" data-macro-name="toc" data-macro-parameters="maxLevel=2" data-macro-schema-version="1" /></p><p><br /></p>",
    "syncRev":"0.izAFz9oUJgl5fEP4WzBEKKI.1",
    "pageVersion":1
}

可以看到之前请求返回的数据在这步操作中需要使用到.

插入 markdown 宏

和插入目录宏类似.只是请求参数稍有变化:

{
    "contentId":"6488066",
    "macro":{
        "name":"markdown",
        "params":{

        },
        "body":""
    }
}

可以看到很简单, 就是 name 指定为 markdown.响应示例如下:

<table class="wysiwyg-macro" data-macro-name="markdown" data-macro-schema-version="1" style="background-image: url(/plugins/servlet/confluence/placeholder/macro-heading?definition=e21hcmtkb3dufQ&amp;locale=zh_CN&amp;version=2); background-repeat: no-repeat;" data-macro-body-type="PLAIN_TEXT"><tr><td class="wysiwyg-macro-body"><pre /></td></tr></table>

这里返回的内容也需要保存下来, 后面的操作需要使用到.

更新文档(draft status)

这是最后一步, 发起 /rest/api/content/{id}?status=draft 请求.请求示例如下:

{
    "status":"current",
    "title":"markdown测试",
    "space":{
        "key":"SPC"
    },
    "body":{
        "editor":{
            "value":"<p><img class="editor-inline-macro" src="http://localhost:8090/plugins/servlet/confluence/placeholder/macro?definition=e3RvYzptYXhMZXZlbD0yfQ&locale=zh_CN&version=2" data-macro-name="toc" data-macro-parameters="maxLevel=2" data-macro-schema-version="1" data-macro-id="50c89389-2ea5-43cf-a582-d5b2ed3d4796" /></p><table class="wysiwyg-macro" style="background-image: url('http://localhost:8090/plugins/servlet/confluence/placeholder/macro-heading?definition=e21hcmtkb3dufQ&locale=zh_CN&version=2'); background-repeat: no-repeat;" data-macro-name="markdown" data-macro-schema-version="1" data-macro-body-type="PLAIN_TEXT"><tbody><tr><td class="wysiwyg-macro-body"><pre># 概要<br /><br />本文档描述了...</pre></td></tr></tbody></table><p><br /></p><p><br /></p><p><br /></p>",
            "representation":"editor",
            "content":{
                "id":"6488066"
            }
        }
    },
    "id":"6488066",
    "type":"page",
    "version":{
        "number":5,
        "message":"",
        "minorEdit":false,
        "syncRev":"0.yM8srPzow93w6esMsDjIuXE.2"
    },
    "ancestors":[
        {
            "id":"5898241",
            "type":"page"
        }
    ]
}

可以发现请求中的 editor 中的数据, 是把第一步和第三步返回的数据拼接在了一起, 并且在第三步返回的数据中插入了我们实际要写入的 mardown 的内容.

1	<table class="..." style="..." data-macro-body-type="..."><tr><td class="...">在这里插入实际的 markdown 内容<pre /></td></tr></table>

通过以上的 4 个步骤我们就可以完成通过程序自动化地在 confluence 中创建 markdown 文档.

感谢您的阅读，本文由 ykgarfield 版权所有。如若转载，请注明出处：ykgarfield
文章链接: https://ykgarfield.github.io/2018/12/23/文档工具/confluence/confluence-如何通过程序在-confluence-中创建-markdown-文档/

confluence-记一次 confluence markdown 表格样式不美观发生的事

xwiki 文档迁移到 confluence-1 迁移方案