如何从 Github/Gitbook 迁移 Wiki 到 Seafile

用 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 的首页内容。如下图所示。

如何从 Github/Gitbook 迁移 Wiki 到 Seafile_第1张图片

其中 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/),感兴趣的用户可以去下载使用,欢迎大家反馈意见!

你可能感兴趣的:(如何从 Github/Gitbook 迁移 Wiki 到 Seafile)