V2EX = way to explore
V2EX 是一个关于分享和探索的地方
现在注册
已注册用户请  登录
爱意满满的作品展示区。
xjqkilling
V2EX  ›  分享创造

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

  •  1
     
  •   xjqkilling · 2019-03-08 17:34:57 +08:00 · 3102 次点击
    这是一个创建于 1847 天前的主题,其中的信息可能已经有所发展或是发生改变。

    经常在各个版上看到很多 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

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

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

    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 这些工具兼容。

    其他特色功能

    除了上述亮点功能外,Seafile Docs 还提供了很多其他功能,主要包括:

    • 知识管理功能:比如给文档加标签,为文档关联相关文档
    • PSD, AI, XMind 等常用的研发类文件的在线预览
    • 多人实时协同编辑功能(开发改进中)
    • 文档格式问题提示,对常见的文档格式问题(比如缺少标题)进行分析和提示(会持续开发改进)
    • 全面的网盘基础功能,可以管理任意类型、任意大小的文件,并提供多终端文件同步

    更多功能可以到官网进一步了解。

    安装与使用

    如果你对上述功能感兴趣,可以访问 Seafile 官网了解如何开始部署或者使用。我们目前提供了两种方式:

    • 你可以下载 Seafile Docs 社区版的 docker 镜像自行安装部署
    • 也可以使用我们提供的 SaaS 服务(目前在免费内测阶段)

    欢迎大家试用和提出反馈意见,我们在快速迭代产品。

    第 1 条附言  ·  2019-03-09 10:59:38 +08:00

    正文里面没有贴图,这里补充几个图,可以更直观了解。

    Markdown 所见即所得编辑

    文档草稿与评审功能

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

    ⭐️评审页可以选择文件内容进行评论。

    ⭐️查看评论的时候,点击引用的内容可以跳转到相应的内容

    ⭐️评审页可以快速的定位修改的内容

    维基页面效果

    3 条回复    2019-05-16 20:38:42 +08:00
    lemonda
        1
    lemonda  
       2019-03-08 23:58:36 +08:00
    刚准备试试各种 Markdown 编辑器就看到这个
    可否发布 Docs 到 WP 博客?
    xjqkilling
        2
    xjqkilling  
    OP
       2019-03-09 11:01:15 +08:00
    @lemonda 目前还不支持,你可以尝试把 markdown 文件编辑好之后,转换到 WP 格式。
    aliangddd
        3
    aliangddd  
       2019-05-16 20:38:42 +08:00 via iPhone
    效果不错
    关于   ·   帮助文档   ·   博客   ·   API   ·   FAQ   ·   我们的愿景   ·   实用小工具   ·   999 人在线   最高记录 6543   ·     Select Language
    创意工作者们的社区
    World is powered by solitude
    VERSION: 3.9.8.5 · 26ms · UTC 19:52 · PVG 03:52 · LAX 12:52 · JFK 15:52
    Developed with CodeLauncher
    ♥ Do have faith in what you're doing.