使用 Markdown + Vivliostyle 创建交付文档的故事

大家好，我是 Tomi (@tommyecguitar)，是制造业的软件开发工程师。

以前在公司做个文档解释交付成果，当时我也试过用 Markdown 排版，所以我想总结一下我是怎么用的，哪里出了问题，优点和缺点。

有很多博客是用 Vivliostyle 排版的，所以请到那里看看它的样子。Vivliostyle 网站请看。

Word还不够吗？

在制造业中创建长文档时，我认为有很多地方通常是多人编辑Word。
但是Word有很多缺陷。

1. 在团队内共同编辑时，编辑的部分会消失，或者字体和设计由于某种原因不统一。
2. 即使您为每个部分划分职责，合并也将是手动的。

   至于前者，如果你将Word设置为共享，并尝试在团队内同时编辑，编辑的内容消失的情况并不少见，可能是因为保存的时间问题。还有，Word有统一设计的功能，但是不知为什么，有些字体变得奇怪，颜色也变了，所以设计管理比较费劲。

   那么，即使你按照职责范围划分文件，然后再把它们放在一起，合并也会手动完成，无法消除人为错误。由于某种原因，我前面提到的设计问题出现了。

   正因为如此，在Word中编辑一个多人的长文档需要格外注意，而且很麻烦！还有什么可以做的吗？ ?它变成了

   Markdown 可以用 CSS 样式化！GitHub 也可以用于合并！

   所以我转向 Markdown。

   Markdown 是一种用标签和参数编写句子的方法，如下图所示，编写时只指定句子的结构，而不考虑设计。 （这被称为标记语言，它就是其中之一。）

   降价示例

   # 見出し1
   
   ## 見出し2
   
   ### 見出し3
   
   何もタグがなければ本文
   
   ![画像の名前](画像URL)
   
   [リンク名](リンクURL)
   

   如果只是 Markdown，设计比较平淡，但是 VSCode 有 Markdown Preview Enhanced 等扩展，稍微研究一下，就可以相对轻松地编辑设计。

   这样一来，编辑器和设计就完全分离了，只要结构写得好，以后就可以对设计进行综合管理了。这解决了Word设计因某种原因而改变的坏处。

   Markdown 的另一个好处是你可以将它与 GitHub 合并。 Word 做不到，所以是手动合并，但是如果用 GitHub 能做到，合并的时候就不用盯着每一句话。

   Markdown + Markdown Preview Enhanced 简单又强大！？

   首先，我寻找可以改变 Markdown 外观的 VSCode 扩展。
   其中，Markdown Preview Enhanced 表现最好。目前，第一个挑战是用这个写一个测试手稿。

   此扩展允许您指定自定义样式，如果您有一些 CSS 或 Tailwind 知识，您可以指定基本设计。易用性相当高，默认样式也很酷，所以从这个意义上说它可能是最强的。

   但是，Markdown 也有一些不好的地方。

   就是这样的Markdown，但是能不能做到和Word一样的事情就不好说了。比如当你想给一个图加标题或者调整图的大小时，不能用Markdown表示法写，所以突然要在Markdown中写一个html的img标签。

   没关系，但是从整体设计的角度来看，样式可能不会仅反映在该图表中，因此我希望尽可能避免它。

   因此，我想编写一个样式规范扩展，即使直接编写html也可以处理，如果可能的话，至少在Markdown中进行标题大小规范。

   那是我发现 Vivliostyle 的地方。

   当我查找它时，我发现那里有人用 Markdown 写书。
   其中有很多人使用了一个叫做 Vivliostyle 的工具，所以我考虑介绍它。

   符号是 VFM

   在 Vivliostyle 中，为了解决 Markdown 发痒的部分，视觉调频使用符号。基本和Markdown一样，但是可以很方便的指定class，不用直接写html就可以指定图的caption和size。
   （它并不完美，但比 Word 的可编辑性要好。）

   VFM 示例

   # クラス指定はこうする{.class-name}
   # idはこうする{#id-name}
   

   使用 SCSS 进行样式设置。您可以更改每个页面的样式。

   具体使用方法可以看官网和各种人的博客，不过是指定样式的方便的地方。

   Vivliostyle 基本上将每一章的 Markdown 文件分开。它不一定是那样，但它似乎应该是可操作的。
   例如，通常希望将封面、目录和文本的设计分开。与以前一样，类指定没有问题，但 Vivliostyle 允许您将这个 CSS 应用于封面，并将另一个 CSS 应用于文本。 Markdown Preview Enhanced 等知名扩展无法做到这一点。

   轻松的 PDF 输出

   无论是 Markdown Preview Enhanced 还是 Word，在转换为 PDF 的时候都有些令人沮丧。

   • 字
     • 画质很烂
     • 字体嵌入可能失败
     • 我不能使用 svg 太糟糕了
   • Markdown 预览增强
     • 背景可能无法导出
     • 字体可以被替换

   与此相比，Vivliostyle 目前已经解决了所有问题。

   我自己先试过

   暂时我也是第一次使用，所以一边参考了各种博客，一边尝试了Create Book。
   这篇文章会有所帮助。

   把 Node.js

   据说使用 Vivliostyle 需要 Node.js 10.0 或更高版本，所以我安装了它。

   现在可以用npm了，但是最近有资料说yarn比较好，所以

   npm install -g yarn
   

   我把它放进去。之后，您可以将 npm 替换为 yarn。

   安装 Vivliostyle CLI

   通过在终端中键入以下命令来安装 vivliostyle。

   npm install -g @vivliostyle/cli
   

   创建图书

   移动到要创建文档的目录并执行以下操作以创建所有必要的文件。

   npm create book <directory>
   

   系统会要求您输入设置，但请参阅上一篇文章。

   在这里你会被要求选择一个风格主题，所以选择一个你喜欢的。我认为一本学术技术书会很好。我使用学术主题 theme-academic。

   复制主题

   要创建自定义主题，很容易将其基于默认主题。
   默认主题是./node_modules/@vivliostyle/theme-xxxx，所以复制它并粘贴到你喜欢的地方。最好把它放在文档目录的某个地方。我直接放在文档目录下。就像这样。

   • 图书目录
     • node_modules
     • theme-academic（我刚刚复制的那个）
     • .gitignore
     • 许可证
     • manuscript.md
     • package.json
     • 自述文件.md
     • vivliostyle.config.js
     • （使用 yarn 产生 yarn.lock。）

   定制现已完成。

   如何以团队的形式运营 Vivliostyle

   这是关键时刻。
   为了在团队中进行操作，我们必须让其他人可以轻松创建环境，因此我们必须删除不必要的文件并使其尽可能易于使用。

   看文件夹结构

   此时的文件夹结构如上所述。
   theme-academic 的内容是这样的。

   • 主题-学术
     • 示例
     • scss
     • 更改日志.md
     • 许可证
     • package.json
     • 自述文件.md
     • theme_common.css
     • theme_common.css.map
     • theme_print.css
     • theme_print.css.map
     • theme_screen.css
     • theme_screen.css.map
     • vivliostyle.config.js

   example 有一个手稿的 Markdown 示例，而 scss 有一个 scss 文件。 *.css 是将这些 scss 编译为 css 的结果。

   这里，CHANGELOG.md、LICENCE、package.json、README.md、vivliostyle.config.js 与父文件夹的内容重叠。 CHANGELOG.md、LICENCE 和 README.md 与文档创建无关，因此如果不需要，可以将其删除。

   package.json 和 vivliostyle.config.js 的内容与父文件夹不同。

   vivliostyle.config.js是创建文档的配置文件，所以theme-academic中的那个是从example创建的配置，父文件夹是从manual.md创建的文件。对于您的团队想要创建的文档，您不需要多个配置文件，所以最后，只需要一个就可以了。

   package.json 是一个文件，它总结了包含文档生成所需的包的设置以及可用于使用 npm 和 yarn 生成文档的命令。在没有任何包的环境中，

   npm install
   

   将读取 package.json 的内容，安装必要的包，并将它们放在 node_modules 文件夹中。

   在这里，我对比一下父文件的package.json和theme-achademic，theme-achademic里面的那个功能比较多，所以决定用那个。

   如果你仔细想想，你可以用theme-academic中的文件来完成它。

   正如您现在可能已经猜到的那样，theme-academic 中的文件就是您所需要的。
   因此，虽然我创建了一本书，但我会全部删除。 （微笑）

   摆弄设置。

   我从父文件夹中删除了除了 theme-academic 之外的所有内容，现在 theme-achademic 是顶层目录。

   我还删除了不必要的文件并使其成为这样。 （css是在构建时生成的，所以不是必需的。）

   • 图书目录
     • md（重命名示例）
     • scss
     • package.json
     • vivliostyle.config.js

   哦简单

   摆弄 package.json

   这个因人而异，但是如果你改变上面的文件夹结构，你必须改变package.json中的设置。尤其是build 脚本的sass 系列文件夹名称、files 值等。这取决于这里的人，所以请尽力而为。

   摆弄 vivliostyle.config.js

   这是装订设置，请参考官方文档进行设置。

   尽可能仔细地编写 README

   我想这是因为我们是在制造业，但是有很多人习惯了Word，不使用Markdown来创建文档。

   幸运的是，这很容易，因为我刚刚安装了 Node.js 并在途中完成了 npm install。

   在 GitHub 上！

   在这个状态下在 GitHub 上管理它。你做到了。

   Vivliostyle 也有它的缺点。

   方便的 Vivliostyle 仍然有其缺点。
   好像还有更新的计划，所以新建文档的时候应该检查一下。

   重置计数器有点困难

   到目前为止，第一个不便之处是难以重置计数器。
   我认为你用css写计数器设置来设置章节号和子号，但取决于你在重置数字时是否写@page，它可能会或可能不会正常工作......

   标题的符号仍然

   图像说明现在更容易了，但表格说明似乎还没有在 VFM 中。
   没办法，只能直接写html了。

   毕竟它是基于 Markdown 的，所以想到它在某种程度上是无济于事的并使用它会很好。

原创声明：本文系作者授权爱码网发表，未经许可，不得转载;

原文地址：https://www.likecs.com/show-308626139.html