前段时间将写作工具全面切换asciidoc后，对asciidoctor也有了进一步定制的要求，仔细看了下官方文档后，一般的定制他已经考虑到了，可以通过配置或者命令行灵活简单的完成，对于复杂一点定制或改造，由于他是开源的，所以也非常容易。下面是自己积累的一些笔记，供大家参考。

语言汉化

目前官方多语言支持还不太好，参考文档和源码的第361行。

  • 官方也提供了一个解决方案，就是在具体的adoc文件中通过include来修改中文翻译，如： include::https://raw.githubusercontent.com/asciidoctor/asciidoctor/master/data/locale/attributes-zh_CN.adoc[]。这个方法试了下可以解决问题，但是侵入太大，不是一种优雅的解决方案。

  • 另外还有一种方案，是通过命令行 -a 将修改部分变量，缺点则是命令行会很长，而且能修改的变量非常有限。

  • 由于文档基本都是中文的，最好默认配置就是中文，好在ruby是解释型脚本语言，可以自己动手修改本地运行的源码，修改方法如下：

    1. Mac下 brew install asciidoctor 安装方式的修改位置为：/usr/local/Cellar/asciidoctor/2.0.6/libexec/gems/asciidoctor-2.0.6/lib/asciidoctor/document.rb，CentOs下 yum install asciidoctor 安装方式的修改位置为：/usr/share/gems/gems/asciidoctor-1.5.6.1/lib/asciidoctor/document.rb，如果不在此目录，可以使用 gem environment 查看 GEM PATHS 具体路径。

    2. 找到如下定义并进行替换修改

      # language strings
# TODO load these based on language settings
attrs['caution-caption'] = '注意'
attrs['important-caption'] = '重要'
attrs['note-caption'] = '备注'
attrs['tip-caption'] = '提示'
attrs['warning-caption'] = '警告'
attrs['example-caption'] = '示例'
attrs['figure-caption'] = '数字'
#attrs['listing-caption'] = '清单'
attrs['table-caption'] = '表格'
attrs['toc-title'] = '本页目录'
#attrs['preface-title'] = '前言'
attrs['section-refsig'] = '章节'
attrs['part-refsig'] = '部'
attrs['chapter-refsig'] = '篇'
attrs['appendix-caption'] = attrs['appendix-refsig'] = '附录'
attrs['untitled-label'] = '未命名'
attrs['version-label'] = '版本'
attrs['last-update-label'] = '更新于'

本页目录

默认不显示目录， 设置参考

  • 目录层级属性：文档中header方式`:toclevels: 5`，命令行：-a toclevels=5

  • 目录标题属性：文档中header方式`:toc-title: 本页目录`，命令行：-a toc-title=本页目录

定制样式

默认是css内置在html中，分离css为独立文件只需要设置属性 linkcss， 设置参考

  • 分离css文件为独立文件属性：文档中header：:linkcss: ，命令： -a linkcss

  • 指定css目录或路径：文档中header：:stylesdir: ../stylesheets ，命令： stylesdir=../stylesheets

  • 指定css文件：文档中header: :stylesheet: customize.css，命令：-a stylesheet=customize.css

增加head和foot

当需要在生成的html5的head标签里增加javascript或者一些meta申明时，可以使用docinfo属性， 设置参考

  • 在所有生成的html的header中增加一个代码片段

    1. 新增 /docinfo/dir/docinfo.html 申明js: <script src="/static/js/toc.js"></script>

    2. 新增 /docinfo/dir/docinfo-footer.html : @copyright liming.pub

    3. 生成命令中增加属性申明： -a docinfo=shared -a docinfodir=/docinfo/dir/

定制模板

看了下官方的 模板仓库，有三个模板技术实现，其中 HAML和 SLIM的设计理念都比较简洁优雅，但是太小众，精力有限放弃学习，ERB类似与JSP，PHP，上手比较快。

具体做法是把官方的模板clone下来，对需要调整的个别模板进行修改，然后在生成的命令里通过 -T 来指定模板路径：

asciidoctor -T /path/to/original/templates -T /path/to/modified/templates mysample.adoc
Note
 多个模板文件夹时，在后面指定的文件夹中的模板文件会顶替掉前面文件夹中的模板，通过这种方式，可以实现增量修改模板。

流程图

  1. 使用rvm来升级ruby

gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB
curl -sSL https://get.rvm.io | bash -s stable
rvm list known # 选择最新的版本
rvm install 2.6

  1. 安装插件

gem install asciidoctor-diagram
#yum install graphviz #暂时不需要

  1. 转换命令

asciidoctor -r asciidoctor-diagram test.adoc

  1. 中文乱码 参考：https://www.jianshu.com/p/faa90891696a

Note
 如果访问不了raw.githubusercontent，可以在https://www.ipaddress.com/查询raw.githubusercontent.com的真实IP。然后在/etc/hosts里增加一条ip映射即可。

生成文档

可以使用如下命令一键生成电子书或者html网站，其中 -D 参数是目标文件夹，可以直接配置为nginx的root目录:

cd src
asciidoctor -D /var/www/document -R . '**/*.adoc'

一个完整可用的生成文档命令：

asciidoctor -r asciidoctor-diagram -a nofooter -a sectnums -a icons=font -a source-highlighter=highlightjs -a linkcss -a stylesdir=/static/css/ -a stylesheet=style.css -a toclevels=5 -a toc=right -a toc-title=本页目录 -a last-update-label=更新于 -a sectanchors -a idprefix! -a docinfo=shared -a docinfodir=/static/meta/ -D /var/www/document -R . '**/index.adoc'
Note
 stylesdir 和 docinfodir 为了保证asciidoctor程序和nginx都能找到，可以考虑使用软连接使两个目录保持一致，语法： ln -s 被连接原目录 软连接目录