用 Seafile 提升发布文档效率

Markdown 因其易用性已成为软件文档的首选格式，有的研发团队会产出大量 Markdown 文档，并需要将这些文档公开发布出去，方便大家查阅资料。Gitbook 是目前最流行的 Markdown 文档发布工具，很多人会使用它来发布 Markdown 文档，但 Gitbook 在Markdown 文档的编辑、管理上都需要借助第三方工具，导致文档发布的流程较为繁琐。而 Seafile 7.0 可以作为一站式的 Markdown 文档发布平台，文档的编辑、管理和发布都可以在 Seafile 系统内部完成，能够带来 Markdown 文档发布效率的显著提升。

关于如何使用 Seafile 来对外发布文档，我们已经在 上一篇文章 中介绍过了。

下面我们对 Seafile 和 Gitbook 进行一下对比，并简单介绍 Seafile 的文档发布流程。

Seafile 和 Gitbook 对比

Gitbook 是一个基于 Markdown 的文档制作和发布工具，但 Gitbook 本身并不具备 Markdown 文档编辑功能，所以你需要在本地安装一个离线的 Markdown 编辑器（比如 Typora）。同时由于国内很难顺畅地访问 Gitbook 网站，所以文档源码只能保存在 Github 上，你不得不再下载一个 Git 工具来将文档源码 push 到 Github 上。

安装了 Git+Typora+Gitbook 之后，通常的发布流程是你需要先在电脑本地编辑 Markdown 文档，再 push 到 Github 项目上托管你的文档源码，最后通过 Gitbook 自动同步 Github 的项目完成文档的编译、发布，这种方式流程繁琐而且效率不高。

总结下来 Gitbook 有以下几个不方便的点：

• 只能用于发布 Markdown 文档，编辑、管理 Markdown 文档要依赖第三方工具
• 发布流程繁琐，效率不高

针对以上痛点，Seafile 7.0 则可以看作是一个集 Markdown 文档的编辑、管理、发布于一体的 Markdown 文档发布平台。Seafile 本身就提供了所见即所得的 Markdown 编辑器，让用户可以直接在浏览器中对 Markdown 文档进行编辑，编辑完成后文档可以直接保存在 Seafile 系统中。当你想对外公开发布软件文档时，你可以创建一个资料库，在资料库中编辑多个 Markdown 文档，然后将资料库以维基的形式公开发布出去。相比 Gitbook 的发布流程，省去了从 github 下载、push 、再发布到第三方文档平台的麻烦。

如果你还想同时保留原有的工作流程（发布到 Gitbook 平台），你也可以使用 Seafile 的同步客户端将维基对应的资料库同步到你的本地电脑上，然后用 git 将改动从电脑 push 到 github。这样相当于把 Seafile 作为一个优秀的Markdown编辑平台来使用，其好处是你可以在编辑时立即看到效果，不需要 push 到 github 上看。由于 Seafile 将维基页面保存为纯文本的 Markdown 文件，所以可以无缝与 github、git 这些工具兼容。

总结下来 Seafile 相比 Gitbook 有以下几个优势：

• 无需下载任何工具，在浏览器中就可以完成对 Markdown 文档的编辑、管理和发布
• 发布流程简单，效率显著提升
• 将维基页面保存为 Markdown 文件，与 Github、Git 无缝集成

迁移现有的 Github/Gitlab 上的 Wiki 到 Seafile

目前很多研发团队已经使用了 Github 或者 Gitlab 自带的 Wiki 功能来管理文档，那么是否可以轻松地从这些平台将文档迁移到 Seafile 呢？答案是肯定的。下面给大家介绍迁移的过程。

由于 Seafile 的 Wiki 也是采用纯文本的 Markdown 格式保存文件的，所以与 Github, Gitlab 的兼容性良好，文档的语法基本不用改动。以下是迁移的简单过程。

第一步：把文档导入 Seafile

首先你要将 Github 或者 Gitlab 中的 Wiki 下载到本地一份，解压到一个目录里面。然后在 Seafile 中新建一个资料库，把这个本地目录里面的文件和子目录直接拖动到浏览器窗口中，即可快捷上传。

第二步：创建 index.md 和 home.md 文件

在 Seafile 的 Wiki 中，index.md 文件用于设定页面左边目录树的内容，而 home.md 则用于展示 Wiki 的首页内容。如下图所示。

其中 index.md 的格式与 Gitbook 使用的 SUMMARY.md 格式基本一致，都是通过列表嵌套的级别来表示目录的级别。文件中原有的相对路径链接也是可以直接使用的。需要注意的是，index.md 中每一级列表的缩进必须是两个空格，否则无法识别。

而 home.md 的作用与 Gitbook 的 README.md 的作用一样，所以如果你之前使用的是 Gitbook，可以直接将 README.md 重命名为 home.md。

第三步：发布文档

回到资料库界面点击左侧工具栏“已发布的资料库”，再点击正上方的“发布资料库”按钮，选择资料库提交即可完成发布。

Seafile 7.0 版本现在已经发布到了 Seafile 的官网（https://www.seafile.com/download/），感兴趣的用户可以去下载使用，欢迎大家反馈意见！