Is there a way to link to CSS instead of embedding it?

[kriegaex]

• Bug report
• Feature request
• Question

Description

Using the Maven plugin, I am creating dozens of HTML files from asciidoc files. Each one of them embeds a significant amount of CSS. As all the generated docs will end up on the same website, I am wondering if there is any way to generate CSS just once and automatically link to it from each HTML file.

I am not very experienced in all things Asciidoctor, but I read about safe mode and linkcss. What I do not know, is whether I can set those options centrally as a Maven plugin option or need to edit each single file to have the same settings. I found no examples setting those attributes here or in the Maven plugin examples repository.

If it is relevant, I still need to be using include:: in some documents.

BTW, I searched the web and Stack Overflow for an answer, but did not find any.

[kriegaex]

OK, I am stupid and ugly:

<configuration>
  <attributes>
    <!-- Create separate CSS files, rather than embedding CSS into each HTML file -->
    <linkcss>true</linkcss>
    <preserveDirectories>true</preserveDirectories>
    <relativeBaseDir>true</relativeBaseDir>
  </attributes>
</configuration>

Now, the total size of my documentation is significantly smaller, even though the asciidoctor and coderay CSS files are still created once per subdirectory, probably because I use relative directories and want to preserve the directory structure. This is mainly due to the fact that I also want asciidoc preview to look nice when browsing the docs on GitHub, and there I do not have any root folder like on the website. And because I am generating different types of manuals residing in different subdirectories with one command, I do not want everything to be flattened.

Do you have any idea how to still use just one set of CSS files for everything without manually adding information to the header of each ADOC file?

[abelsromero]

I am not very experienced in all things Asciidoctor, but I read about safe mode and linkcss. What I do not know, is whether I can set those options centrally as a Maven plugin option or need to edit each single file to have the same settings.

The plugin is a wrapper around asciidoctor CLI command (embedded in AsciidoctorJ library, not running Ruby process). Preciselly it helps to centralize configurations so they are applied to all docs, the cli works 1 document at a time, so the plugin simply iterates over them adjusting paths accordingly.
Any reference to an Asciidoctor attribute in the docs means you can set that in the plugin's <attributes> block if you don't want to put it in every single document.

I found no examples setting those attributes here or in the Maven plugin examples repository.

It's tough to decide what we put in the examples, we can't cover everything, At the end we settled to focus on integration configuration, not options/attributes configurations, sorry.

I am wondering if there is any way to generate CSS just once and automatically link to it from each HTML file.
Do you have any idea how to still use just one set of CSS files for everything without manually adding information to the header of each ADOC file?

You can hack it with multiple executions:

1. First, one to render a dummy file to generate the css.
2. Then, another to render the final files, for that you can use https://docs.asciidoctor.org/asciidoctor/latest/html-backend/custom-stylesheet/ attributes to set the final path. The attributes can be set in the sources or the plugin configuration under the <attributes> block.
   Or if you want to void multiple executions, render the css once and commit as a source, then simply configure stylesheet and stylesdir as in (2).

For this to work in a published site, I think (not CSS expert myself) you'll need to set the path as absolute in the root "/my-style.css", that will work on a web environment, but not locally though.

BTW, I searched the web and Stack Overflow for an answer, but did not find any.

The best way to get general asciidoctor support is in Zulip http://chat.asciidoctor.org/.

This is mainly due to the fact that I also want asciidoc preview look nice when browsing the docs on GitHub

Apologies in advance, I don't mean to be rude, but my suggestion is to not try. GitHub does not use the most recent version of Asciidoctor and does not support all features (links and includes for instance). GitLab offers a better experience and even then it's not going to be the same as rendering your content.
You can instead set GitHub pages to show the generated HTML for a perfect rendition.

If you have a WIP public repo, feel free to point it.

[kriegaex]

I found no examples setting those attributes here or in the Maven plugin examples repository.

It's tough to decide what we put in the examples, we can't cover everything, At the end we settled to focus on integration configuration, not options/attributes configurations, sorry.

I understand. I was mentioning it, because I wanted you to know that I searched before asking - due diligence.

BTW, I searched the web and Stack Overflow for an answer, but did not find any.

The best way to get general asciidoctor support is in Zulip http://chat.asciidoctor.org/.

Good to know, thanks for the link. Yet another new chat tool, sigh. I already use so many: Telegram, Gitter, WhatsApp, Slack, Teams. But at least, it is not IRC, which would be worse. 😉

I also want asciidoc preview look nice when browsing the docs on GitHub

my suggestion is to not try. GitHub does not use the most recent version of Asciidoctor and does not support all features (links and includes for instance).

I know it does not support includes and GitLab does, but I will not move the repo just because of that. And I said "nice", not "perfect". If at least each single ADOC is rendered correctly with included pics, that is good enough for now. Currently, this is the case.

You can instead set GitHub pages to show the generated HTML for a perfect rendition.

Well, that is the exact reason why I am using the Maven plugin: to create static HTML for GH Pages and for packaging the docs into the binary distro used in the executable JAR installer. But still, when simply browsing the GH repo while looking for something, it is desirable to me to be able to see something meaningful when clicking on an ADOC file. I might have changed something, but not updated the website, because I only plan to do that for releases, not in between - at least not often.

If you have a WIP public repo, feel free to point it.

The project is Eclipse AspectJ. Start at this landing page ADOC in my asciidoc branch:
https://github.com/eclipse-aspectj/aspectj/blob/docs-to-asciidoc/docs/index.adoc

The current count is 118 asciidoc files. Then look around, especially in parts of the table for which there are 3 links (multi page HTML, single page HTML, PDF). The latter two will only work on the website, because rendered PDF and HTML are not in the SCM, of course. Multi page HTML would work on GitLab, I know, but... see above.