Seafile Docs -- 基于 Markdown 的研发文档管理平台，支持所见即所得编辑

V2EX = way to explore

V2EX 是一个关于分享和探索的地方

现在注册

已注册用户请登录

爱意满满的作品展示区。

这是一个创建于 2116 天前的主题，其中的信息可能已经有所发展或是发生改变。

经常在各个版上看到很多 V 友讨论关于 Markdown 所见即所得编辑的问题，也有不少 V 友做了一些好用的工具，感觉在研发同学中间 Markdown 文档的编辑和管理还是比较有需求的。但是目前的方案以及工作流程个人感觉有几个痛点：

需要手工写 Markdown 的语法格式，不能直接看到文档的最终效果。虽然我并不抗拒写 Markdown 语法，但是如果能够更快捷直观地输入各种格式，能大大提高写作的效率。类似 CodeMirror 这样的组件虽然能看到编辑效果，但是还是无法避免 Markdown 语法，且只提供了预览，而不是“所见即所得”的方式。
表格和图片的插入和编辑比较痛苦。目前的大多数方案都只能用语法来手写表格，写起来比较累；而插入图片还需要先上传到其他地方（或者类似 github 这种先保存到 git 里面），再插入一个链接。
缺少一体化的 Markdown 文档编辑、管理、发布平台。现在很多同学发布文档的方式是：先在 github 上面创建一个文档项目；下载到本地编辑（或者在 github 上编辑），编辑过程要么是直接写语法，要么是用一些界面友好的本地 Markdown 编辑器； push 到 github，看最终效果；在第三方的文档发布平台（ gitbook, readthedocs ）上面配置自动同步 github 上的项目，第三方平台编译并更新文档。这个过程是比较繁琐而且效率不高的。

针对这些常见的痛点，结合我们团队内部的日常需求，Seafile 团队基于 Seafile 开发了一个基于 Markdown 格式的研发文档管理平台 -- Seafile Docs。Seafile 一款开源的企业网盘产品（https://www.seafile.com），Seafile Docs 是在 Seafile 基础上开发的面向研发文档管理的增强版。

Seafile Docs 目前具有几个主要的功能亮点，下面简单介绍一下。

Markdown 所见即所得编辑

支持在浏览器里面以所见即所得的方式编辑 Markdown 文件，具有以下特点：

像编辑 word 文件一样编辑 Markdown 文件，简单直观。
轻松插入图片、表格、链接、列表。你可以直接在文档中上传一个图片，还可以调整图片的显示大小，图片会作为一个文件保存在 Seafile 里面；轻松插入表格并增删行和列。
文档保存为纯文本 Markdown 格式，轻松从 Github 导入导出。

文档 Draft 和 Review

文件草稿和评审用于满足以下的使用场景

你不希望写到一半的文档被当做正式文档。
频繁保存文档，会产生大量的历史记录，先生产草稿再合并，原文件就只有一个历史记录。
文档管理员不希望文档在没有审核的情况下被他人修改。尤其是如果一篇文档已经发布，现在需要在上面添加一些新内容的时候。

Draft （草稿）类似于 Git 里面的分支，先给需要修改的文档创建一个草稿，修订完成之后再发布，而不是一保存其他人就能看见。而 Review （评审）则类似于 GitHub 上的 Pull Request，可以邀请其他人来评审对一个文档的修改。我们希望通过这个功能，使文档能像代码一样经过 review 之后再发布，提高文档的质量。

评审人可以在评审页查看文件的修改（内容 diff ）和文件的历史版本。评审人也可以选择文本并进行评论。

利用公开维基对外发布文档

Seafile Docs 还可以作为一个一站式的软件文档发布平台。你可以在上面创建一个资料库，在里面编辑多个 Markdown 文件，然后将这个资料库以维基的形式来对外发布，省去现有流程中从 github 下载、push、再发布到第三方文档平台的麻烦。维基页面的效果可以参考下图。

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