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

Question

Is there a 'native' way to include your own HTML, CSS and Javascript page in an Antora generated site?

Including an HTML file in the Asciidoc source with inline CSS styling works for only HTML and CSS like this (see the attached image for the result):

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

However, if you were to separate the CSS out and add Javascript then the .css and .js files do not get published since they are not directly included anywhere and the included HTML follows the styling defined by the UI bundle.

Manually copying the CSS and Javascript files to the right place in the build files works as expected (the Antora page is styled and runs the .js as expected)

I would think most Antora documentation is the product of some CI/CD pipeline so you could probably add the CSS and Javascript to the build files as part of the pipeline but that is a messy solution.

What is really required is a way to force Antora to publish some 'extra' files or folders.

I get that the whole point of Antora is to make consistently styled and formatted documentation. The reason for wanting to do this is to include interactive graphs generated by Plotly or Bokeh in the documentation.

It also opens up the possibility of including any kind of interactive window, such as a button to play music. In my case I want to have an 'interactive chord book' that plays and highlights the notes in music chords.

Inline Styling on Antora Site

Answer 1

Your sample pass-through block works because the included file is inserted into the content flow at that position. The test.html file is not, itself, published, but its contents exist within the file using the include macro.

Similarly, if you used this partial block:

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

The contents of test.js are injected into the content flow at that point. test.js itself doesn't need to be published if you are simply embedding a few lines of code.

If you do need test.js to be published, you have three choices:

1. Store test.js in the module's attachments folder (instead of partials. The partials folder is intended to contain "small" Asciidoc documents that are used multiple times). You'd need to include::attachment$test.js[], but that file does get copied to the build folder.

2. Use supplemental_files: https://docs.antora.org/antora/latest/playbook/ui-supplemental-files/ Supplemental files allow you to customize the assets in the UI.

3. Fork the UI and add your customizations directly.

The latter two approaches would be preferable. Currently, Antora only publishes HTML. In the future, publishing to other output formats may occur, including to PDF. PDFs won't work well with embedded HTML, CSS, or JavaScript, so the UI customization is the preferred approach. (PDF generation will likely have a distinct theme support, similar to asciidoctor-pdf).