自动生成Asciidoctor输出
我被要求为我当地大学的下一学期设计新课程。 从历史上看，我使用Power Point创建课程幻灯片，并使用Word创建实验说明。 对于幻灯片和文档，还有其他可能的替代方法：
- Google幻灯片
- 一堆JavaScript框架（ Reveal.js ， Impress.js等）
- 专用的在线学习平台（ Moodle等）
- 等等
我最近还用Asciidoctor编写了一些实验室文档，并使用Git进行了版本化。 构建过程会生成HTML页面，并将它们托管在GitHub页面上。 每次按下都会触发构建。
该解决方案对我有几个优点：
- 我完全控制媒体。 Asciidoctor文件保存在我的硬盘驱动器上，以及我想要的任何其他Git存储库（无论是公共的还是私有的）都存储在云中或自托管。
- 该Asciidoctor格式编写的文档真的很棒。
- 与一个源文件中，可以有多种输出格式（.eg HTML，PDF等）。
- 托管在Github / GitLab Pages上HTML可以自动生成，用于遥控器上的每次推送。
初始点
设定
对于课程和实验，设置略有不同。
培训班
要显示幻灯片，让我们使用Reveal.js。 幸运的是， Asciidoctor Reveal.js允许从Asciidoctor源生成幻灯片。 使用Ruby，由于文档的原因，设置非常简单：
- 安装捆绑器：
geminstall bundler - 创建具有以下内容的
Gemfile：source 'https://rubygems.org' gem 'asciidoctor-revealjs' - 配置捆绑器：
bundle config--local github.https true bundle --path= .bundle/gems --binstubs= .bundle/.bin - 最后，生成HTML：
bundleexec asciidoctor-revealjs source.adoc
实际上，在我的情况下，生成命令略有不同：
bundleexec asciidoctor-revealjs -D output/cours \ (1)
-arevealjs_history=true\ (2)
-arevealjs_theme= white (3)
-arevealjs_slideNumber=true\ (4)
-a linkcss \ (5)
-acustomcss= ../style.css \ (6)
-arevealjsdir= https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0 (7)
cours/ * .adoc (8)- 设置HTML输出目录
- 在每个导航步骤中，将URL明确推入浏览器历史记录中
- 使用白色（默认情况下为黑色）
- 显示幻灯片编号-仅供参考
- 创建一个外部CSS文件，而不是将样式嵌入到每个文档中-如果存在多个文档，则很有意义
- 覆盖某些样式
- 引用要使用JavaScript框架-可以是本地位置
- 生成属于一个文件夹的所有文档-而不只是一个特定的文档
实验室
从Asciidoctor生成标准HTML文档更加容易：
bundleexec asciidoctor -D output/tp tp/ * .adoc自动远程生成
本地自动化
到目前为止，一切都很好。 一切正常，每次按遥控器都会生成该站点。 唯一的缺点是，为了预览该站点，必须要么推送...要么每次都键入整个命令行。 bash历史记录会有所帮助，直到需要其他命令为止。
作为用户，我想自动预览HTML，以免我一遍又一遍地编写相同的命令行。
这一点比较困难，因为它与Asciidoctor不相关。 带有LiveReload的成熟解决方案以及所有内容都可能会被视为过大（请看我太懒了）。 但是，我对监视本地文件系统以及检测到更改时的命令触发感到非常满意。 当我的笔记本电脑在OSX上运行时，这是一个“可在我的计算机上工作”的解决方案。 这基于启动的过程和plist格式。
这种格式是基于XML的，但是是“弱类型的”，并且基于元素的顺序。 例如，键值对定义如下：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plistversion="1.0">
<dict>
<key> key1 </key>
<string> value1 </string>
<key> key2 </key>
<string> value2 </string>
</dict>我必须自己找出几件事-我以前没有关于launchd的经验：
-
.plist文件应按照名为Label的键命名。 - 它应该位于
~/Library/LaunchAgents/文件夹中。 - 在这种情况下，最重要的部分是了解如何监视文件系统 。 这是通过与要观察的路径数组关联的
WatchPaths键实现的。 - 第二个最重要的部分是要执行的命令
ProgramArguments。 语法非常复杂：命令行上的每个参数（用空格分隔）应该是数组中的一个元素。$ PATH似乎没有使用我自己用户的环境变量初始化，因此应使用可执行文件的完整路径。
- 由于调试是强制性的-至少在运行前几次时，请随时使用
StandardErrorPath和StandardOutPath分别在文件中写入标准err和out。
最终的.plist看起来像这样：
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plistversion="1.0">
<dict>
<key> Label </key>
<string> ch.frankel.generatejaveecours.plist </string>
<key> WorkingDirectory </key>
<string> /Users/frankel/projects/course/javaee </string>
<key> Program </key>
<string> /usr/local/bin/bundle </string>
<key> ProgramArguments </key>
<array>
<string> /usr/local/bin/bundle </string>
<string> exec </string>
<string> asciidoctor-revealjs </string>
<string> -a </string>
<string> revealjs_history=true </string>
<string> -a </string>
<string> revealjs_theme=white </string>
<string> -a </string>
<string> revealjs_slideNumber=true </string>
<string> -a </string>
<string> linkcss </string>
<string> -a </string>
<string> customcss=../style.css </string>
<string> -a </string>
<string> revealjsdir=https://cdnjs.cloudflare.com/ajax/libs/reveal.js/3.5.0 </string>
<string> cours/*.adoc </string>
</array>
<key> WatchPaths </key>
<array>
<string> /Users/frankel/projects/course/javaee/cours </string>
</array>
<key> StandardErrorPath </key>
<string> /tmp/asciidocgenerate.err </string>
<key> StandardOutPath </key>
<string> /tmp/asciidocgenerate.out </string>
</dict>
</plist> 要最终启动守护程序 ，请使用launchctl命令：
launchctl load ~/Library/LaunchAgents/ch.frankel.generatejaveecours.plist结论
虽然在每次推送时自动生成HTML页面非常简单，但是在推送之前预览HTML需要手动操作。 但是，通过一些研究，可以扫描文件系统上的更改并在笔记本电脑上自动生成。 以懒惰为荣！
翻译自: https://blog.frankel.ch/automating-generation-asciidoctor-output/