Asciidoctor render_file缺少CSS
Asciidoctor是一个尤其流行的文档编译器。它支持将各种格式的文档编译为多种输出。最常见的输出格式是HTML，但也支持PDF、ePub、DocBook等。但是，在我们使用Asciidoctor将我们的文档编译为HTML时，我们注意到了一个问题。我们的文档没有任何CSS应用，导致HTML输出丑陋难看。
为了解决这个问题，我们需要在HTML输出中应用CSS。在Asciidoctor中，为模板提供样式的最常见方式是使用external CSS文件。然而，我们尝试了其中一些解决方案，如给HTML指定CSS路径，但都没有得到结果。这是什么原因呢？
问题源头
根本原因是Asciidoctor的render_file方法缺少对CSS输出的支持。所以，在使用Asciidoctor时，需要通过转换器来转换而不是render_file来编译文件，以便指定更好的CSS输出。这意味着我们使用以下的代码：
require 'asciidoctor'
require 'asciidoctor/css3'
Asciidoctor.convert_file('document.adoc', to_file: 'document.html', backend: 'html5', safe: :unsafe, attributes: %w(stylesdir=/path/to/stylesheet.css stylesheet=stylesheet))
而不是以下的代码：
require 'asciidoctor'
Asciidoctor.render_file('document.adoc', header_footer: true, safe: :unsafe)
解决方案
这样，在使用Asciidoctor实现HTML输出时，使用下列代码可实现简单的内部CSS：
require 'asciidoctor'
content = Asciidoctor.convert_file 'document.adoc', safe: :unsafe
processed_content = "\n#{content}"
File.write 'output.html', processed_content
而对于应用于外部CSS的更为复杂的解决方案，请参考本文之前介绍的第一个代码块和以下CSS组件：asciidoctor-pdf、asciidoctor-pdf-cjk、asciidoctor-html-converter和asciidoctor-reveal.js。这些组件通过定义output文档的CSS样式来解决这个问题。
此外，我们还可以在我们的源文件中使用Asciidoctor架构标记，以更精细地在文档中定义我们的CSS样式。这些标记的使用可以让我们更好地控制我们的文档输出，以便我们使我们的文档在不同设备上的显示相同，并且更好地支持打印功能。
总结
如果您在使用Asciidoctor时遇到了缺少CSS样式的问题，请务必查看render_file方法并考虑修改调用。此外，针对输入内容的使用CSS样式的最佳方式是将CSS样式和标记放在同一文件中，而不是将它们分离为多个文件。这样做可以简化代码并使调试更简单。
总体而言，为了让我们的Asciidoctor文档在HTML输出上使用CSS，我们需要通过转换器来转换而不是render_file来编译文件，以便指定更好的CSS输出。