如何在 Antora 中包含自定义 CSS、HTML 和 Javascript？

Question

是否有 'native' 方法在 Antora 生成的站点中包含您自己的 HTML、CSS 和 Javascript 页面？

在具有内联 CSS 样式的 Asciidoc 源中包含一个 HTML 文件仅适用于 HTML 和 CSS 像这样（结果见附图） :

++++
include::partial$test.html[]
++++

但是，如果您要将 CSS 分开并添加 Javascript，则 .css 和 .js 文件不会发布，因为它们没有直接包含在任何地方并且包含的 HTML 遵循 UI 包定义的样式。

手动将 CSS 和 Javascript 文件复制到构建文件中的正确位置会按预期工作（Antora 页面已设置样式并按预期运行 .js）

我认为大多数 Antora 文档都是一些 CI/CD 管道的产物，因此您可以将 CSS 和 Javascript 作为管道的一部分添加到构建文件中，但是是一个混乱的解决方案。

真正需要的是强制 Antora 发布一些 'extra' 文件或文件夹的方法。

我知道 Antora 的全部意义在于制作风格和格式一致的文档。想要这样做的原因是在文档中包含由 Plotly 或 Bokeh 生成的交互式图表。

它还开辟了包含任何类型的交互 window 的可能性，例如播放音乐的按钮。在我的例子中，我想要一个 'interactive chord book' 来播放和突出音乐和弦中的音符。

Inline Styling on Antora Site

Answer 1

您的示例传递块之所以有效，是因为包含的文件在该位置插入到内容流中。 test.html 文件本身并未发布，但其内容使用 include 宏存在于文件中。

同样，如果您使用了这个部分块：

++++
include::partial$test.js[]
++++

test.js 的内容在该点注入到内容流中。如果您只是嵌入几行代码，test.js 本身 不需要 发布。

如果您确实需要 test.js 发布，您有以下三种选择：

将 test.js 存储在模块的 attachments 文件夹中（而不是 partials。partials 文件夹旨在包含“小型”Asciidoc 文档多次使用）。您需要 include::attachment$test.js[]，但该文件确实会被复制到构建文件夹中。
使用supplemental_files：https://docs.antora.org/antora/latest/playbook/ui-supplemental-files/ 补充文件允许您自定义 UI.
中的资产
分叉 UI 并直接添加您的自定义项。

后两种方法更可取。目前，Antora 仅发布 HTML。将来可能会发布到其他输出格式，包括 PDF。 PDF 不能很好地与嵌入式 HTML、CSS 或 JavaScript 配合使用，因此 UI 自定义是首选方法。（PDF 生成可能会有独特的主题支持，类似于 asciidoctor-pdf）。

How can I include custom CSS, HTML and Javascript in Antora?