用 markdown 文档完全替代 word 文档的可行性

[shijingshijing]

目前公司正在讨论后续文档管理的策略，在方案选型的时候，在 word 和 markdown 之间有些犹豫。

主要是分析了现有文档管理情况，然后考虑新项目的文档如何管理。大致情况如下：
1.硬件团队的嵌入式的代码直接使用文本文件的 README，甚至用 ASCII 化简图（有非常 nb 的老工程师在驱动代码文件头部用 ASCII 拼除了芯片引脚和寄存器移位的示意图，这种只能膜拜，绝壁是不能动的）。
2.软件团队内部主要使用 Sphinx，部分 java 代码相关的用 javadoc。
3.系统架构、需求方面以 word 文档为主，有不少内嵌的 UML 截图，visio 截图。
4.测试文档也是用的 word 编写，测试用例主要是 excel 模板管理，测试报告也是 excel 套 word 模板生成的，一边测一边填 excel，测完运行一个宏直接生成。
5.用户手册也是用的 Word 模板，然后人工编写。
6.各个部门内部有一些比较好的经验分享类的文章，也是用 word 编制的，很多都是图文并茂。

现在的主要问题是这些文档都是独立的文档，公司想把这些文档做成某种能够在线检索的知识库，同时还要考虑以下问题：
1，去微软化，彻底替换 word，而且不考虑 WPS，文档格式需要能够完全透明，根据自己的需要检索、解析或者批量处理，能用 git 进行版本管理。
2，显示输出要保持同类型 word 文档的层次和条目，不能跟以前老项目的文档看起来有很大不同，细微的差别可以接受。
3，必须能够像 word 那样在 A4 纸上分页打印输出，同时如果在线查看也能像 HTML 那样连续输出一整篇。
4，能够导出成 pdf 作为离线的电子版发布。
5，一篇文章作为一个文件，图片必须内嵌到文章里，不能以链接的方式单独存放。
6，支持离线编辑，支持图文混和编辑，所见即所得。

我已经在 word 上面做了大量尝试，包括使用 sharepoint 来进行版本管理，这套方案还是太厚重了，sharepoint 的版本管理和 git 还不太一样。另外在网上看见有方案是用 BASE64 编码图片然后内嵌到 markdown 文档里面，不知道较大的图片是否可行。文档格式方面其实没有特别复杂的需求，刚性的主要是图文混排，分段，加粗加黑，缩进这些，word 和 wps 的格式其实已经太复杂了，很多功能用不上。

大家有没有其他好的实践，希望能分享一下。

[creanme]

要不试试语雀？

[gtlions]

在一个 api 项目（几十个接口）中开始推广和使用 md，一直到现在，还行，技术类文档一般没啥问题

[shijingshijing]

@creanme 忘记说了，不能依赖任何外网的云服务。github 都不行。

[dreamertn9527]

base64 可行的，不过缺点是文件越大，越长。占用了不少编辑行。我有道云上的图片全是 base64 转的。

[Nasei]

一个图文混排原生 md 就不行了

[ztcaoll222]

markdown 对表格的支持并不完善, 比如分行, 合并, 除非写 html

[tamlok]

vnote and viki

[shijingshijing]

@dreamertn9527 我也比较好奇微软是怎么把 doc 文件里面图文混排做的这么厉害的。我看过有 BASE64 方案是把所有图片放在文章最后，然后正文中用 id 替换。

还没尝试过 LaTex，感觉这个只会更麻烦。。。

[lithiumii]

3 和 4，导出和分页反正不难，markdown 用 pandoc 转 pdf 或者 docx 都挺完美的（完美的意思是足够支持我大学时候的论文排版需求）
别的就不懂了

[shijingshijing]

@Nasei 所见即所得和图文混排主要是有很多非程序员需要使用，比如系统工程师编写系统分析文档，客户服务工程师编写用户手册，word 还是有优势的。

[Nasei]

@shijingshijing 是呢, 当然通过 html 怎么都能弄, 但拓展和标签加多了真的很麻烦, 第三方工具坑也多, 有段时间我甚至用 md 写 ppt 画流程图, 现在还是 office 走起

[Vamposine]

内部文档系统，是不是可以考虑内网搭个 confluence ……或者类似 gitbook 这样的

[shijingshijing]

@Vamposine 是的，这种类 wiki 的其实解决方案还是很多的，我们的难点在与离线编辑和图文混排，还要做到能够在线分享且能够版本管理。

[uhian]

MarkDown 让我想起 dos 时代的 WPS，顺带想起了 CCED，中文之星……

[jorneyr]

不要折腾了，还是用 word 吧！

[iyaozhen]

@shijingshijing 内网 Wiki 速度差不多能当本地 word 用了

[alinwu05]

非技术人员用 md 很困难的，不要太理想化了

[jdhao]

Markdown 复杂排版还是不行，楼上说的表格就是一个弱项，只能处理比较标准的表格，一旦涉及到单元格合并等等，就不行了。另外图片的并列等，也不太好弄，只能 hack。

我最近在写一个文档，就是用 Markdown，然后使用 pandoc 转为 PDF，就需要用到 LaTeX 的一些知识，我自己懂，所以还好，你要做出精美的文档，不懂 LaTeX 是不太行的，但是让普通人学习 LaTeX，感觉难度比较高，不太好推广。

我写了一篇从 Markdown 生成 PDF 的博文，把所有能想到的问题和坑都写了，地址在 https://jdhao.github.io/2019/05/30/markdown2pdf_pandoc/

楼主可以试一下，遇到问题可以交流一哈

[jdhao]

@jdhao 另外关于图片的存储，既然你有 git，可以把图片和 Markdown 源文件放在一个 project，然后 Markdown 直接引用，生成 PDF

[love]

图片干嘛要和文本放在一起，没道理，操作修改和 diff 都不方便。
表格复杂的直接在 md 里写 html 不就完事了。

[dalieba]

LibreOffice 来了解一下

[dalieba]

这个可以依靠 Libo PlantUML 插件在文档里边直接用 UML 作图，须要外接 Graphviz 程序。
https://bbs.libreofficechina.org/thread-2188-1-1.html

[dalieba]

Typora 通吃 Markdown/LaTeX，值得一用。

[tennc]

@dalieba +1

[tennc]

Typora 通吃 Markdown/LaTeX，值得一用。 @dalieba +1

[shijingshijing]

@dalieba 没用过这个 Libo，我们的 UML 都是在 Enterprise Architect 里面弄的，功能强大。Typora 也在用，感觉离完全顶替 word 还差一截。。。

[shijingshijing]

@love 不可能叫做机械和模具的工程师用用 Beyond Compare 就已经不错了，vim diff 什么的太难为人家了，html 估计都得熟悉熟悉才行，负责客户培训的小 mm 也不可能写 html 的。图文混排和所见即所得是刚需。

[kvker]

本质上算是 html 替代 office ？

[shijingshijing]

@kvker 不一定是 HTML，但是应该算是 Markup language 替代不透明的 doc 文档。

[zhuangzhuang1988]

先比的上 reStructuredText 再说吧。
拿个小砍刀去和导弹比。

[secondwtq]

... Markdown “替代” Word 这种话也就只有程序员能说了

这俩（或者说 Word，TeX 这俩和其他标记语言）根本就不是一个定位的东西，没法拿来比的。在功能性上，Word、TeX 和其他标记语言有十分巨大的 gap，并且这个 gap 中间是没有别的选择的，意思是你要么用 ASCIIDoc/reStructuredText，要么用 Word/TeX，要么妥协你自己的需求。（ HTML 勉强能比，但是我觉得你都用 HTML 写东西了，干嘛不用 TeX ？）

你把这些标记语言给拿给非程序员，人家没准会选 BBCode/Discuz! 代码，不为别的，起码人家功能强啊（就算如此好像还是没有解决最基本的图文混排）

另外倒是有一些可视化编辑器很有意思，不过现在这年头的年轻人喜欢什么都往 Web 上面搬，这个歪风邪气本身就喝楼主要求离线的需求是相悖的 ... 所以¯\_(ツ)_/¯

[secondwtq]

@secondwtq 据我所知目前在这个 gap 之间的只有这么几种选择：Markdown 的各种魔幻扩展，PHP，Madoko

PHP 还有的救，Madoko 就是 TeX，Markdown 扩展跟 TeX 比就是这张图： https://gss0.baidu.com/-fo3dSag_xI4khGko9WTAnF6hhy/zhidao/pic/item/c9fcc3cec3fdfc033cfbce23d23f8794a5c226ad.jpg

欢迎举出反例，因为我发现所谓 Markup language 的世界真的太单调了，我非常愿意了解还有几个能打的

[haimall]

看了半天 discuz 论坛最合适了😂😂😂

[geelaw]

呃 首先 docx 是标准化的，可以解压缩查看 XML。其次，自动化的检索等任务可以用 COM。

[AX5N]

标题的主语是谁？

[widewing]

要不。。eml ？ 邮件客户端都能打开，支持可视化排版，图片编码为 ascii，完美标准化。。

[fannas]

看了一遍，latex 完全满足要求。

[fannas]

@fannas sharelatex 和 over leaf 了解一下啦

[silentstorm]

docx 已经全部是 xml 定义了，可以开发一个解析 docx 的程序。

[luozic]

你怕是不知道 word 早就做了规范化文档方案 ，内容都是存 xml 的。 业界好几种索引和检索 word 文档的搜索引擎，商业得好几个，免费还能私有部署的自己找找

[wweir]

解决了技术问题，再来考虑一下人？人、企业的接受能力，才是 office 这套软件最强的生命力

[exip]

用 libreoffice，除非你司都是程序员才有可能都用 markdown

[FrankHB]

不同文档面向的用户和维护需求不同，为什么要强求使用相同的实现？
（要不需要编辑，直接 pdf 都行。）
要强调检索那得结构化数据，都不应该保证存的是“文档”。
去微软化？自己实现个 ISO/IEC 29500 ？

[Stevenv]

顶多只能技术部用 markdown

[FrankHB]

@secondwtq 能打的，是指不“单调”么？ SGML 和 DSSSL 了解一下？（

@exip 要表格什么的 md 就没救的……看这需求是没跑了。
程序员也干不过 markdown 方言兼容和残废（比如 Bitbucket wiki ）问题。

[xuanbg]

除了不能直接画图外，都没有问题。我们直接在 git 项目的 readme.md 里面写接口文档已经好几年了。

[dalieba]

@haimall #33 还有 phpbb、Discource
@shijingshijing #26 那就来看看 http://url.slat.org/dwl-tw

[mapper]

word 是不可能被取代的，更大众化， 同样 markdown 对于技术人员来说也是无法取代的

[FrankHB]

@mapper 不，markdown 的竞争对手和备胎明显更多，个人使用现在能直接上车的就有不少。技术人员只会用 markdown 和某些服务只支持 markdown 会是个问题，但不会是长期的不可实现替代的问题。反过来，Word 不说实现，光是文档规格就别想随便整个替代，甭管你是不是技术人员。

[mooncakejs]

markdown 太简陋了。

[liu19931020]

Sphinx 用 reStructedText 挺好的

[qqjt]

别替代了，老老实实支持多种文件格式，txt、word、markdown 等等。

[snw]

Word 是非专业通用文本编辑器中最好用的，功能很全。

但一旦你想做些专业的事情就会发现 Word 真是 bug 一大堆，样式、字体、表格、修订等等，经常莫名其妙就崩坏。

[littlewing]

confluence

[l1ve]

onlyoffice 不考虑一下？

[lzhCoooder]

LaTeX，全公司用一套大模板，每个部门在上面微调一下，以后每个人写起来就像在做填空题，并且格式完美一致，除了你说的所见即所得，其他需求都是最基本的功能

[qianji201712]

居然用 word 写技术文档 = =（求别碰），MarkDown 标配吧

[jdhao]

@lzhCoooder 表格就比较麻烦，另外 LaTeX 运行出错，debug 也比较麻烦

[liu19931020]

@lzhCoooder 你们的表格做的累不累

[hzgit]

confluence +1

[Shingekinoshinji]

用 latex 的话可以用 lyx 达到所见即所得的目的

[shooter556]

高级程序员每天最重要的工作是画 ppt
md 能画 ppt ？
ppt 不画出花来能唬住客户？

[FrankHB]

@shooter556 直接用 ppt 画 ppt 的基本是电脑中级高手。高级程序员里有不少各路奇葩玩意儿转 pdf 再转 ppt 的……

[xmsz]

如果只涉及开发，Markdown 足以
如果涉及整个团队，肯定要线上第三方
如果涉及整个团队，又不能线上，可以使用第三方部署内网
如果涉及整个团队，不能线上也不能内网部署，那还是自己想用啥就用啥，别强求更浪费时间，大家还不乐意

[PythonKGB]

你们这完全是给自己增加工作障碍。
我就纳闷了，技术文档怎么就不能用 word 写了呢？格式通用，任何人任何电脑都能打开，再复杂的图文混排，就没有解决不了的。
反观 markdown，学习成本不说，你一堆 MD 文档，客户用户手册用这个？外部沟通用这个？还得给各个部门同事安装 md 应用去？
别为了自己的想法，给别人找事儿。

[touno]

说了那么多，让程序员搞一个 CMS 出来就 OJBK 了~直接内容在 CMS 里面编辑发布，HTML 也可以呈现出很多东西，当然要好看还得看前端怎么去搞这些，很多样式都是要靠 CSS 和 JS 渲染的，但是 HTML 自带的足以应对你们普通的文档了。