CSS (Cascading Style Sheets) don't "cascade": only a single CSS, overwriting/ignoring others.

[WaterSibilantFalling]

In general: CSS style sheets should 'cascade'. That's how they are used.

Specifically: I want to modify one of the CSS style sheets that comes with asciidoctor-browser-extension, and then I want to modify that modification in two ways. Great. Cascading Style Sheets! . . . but no: CSS (Cascading Style Sheets) don't "cascade": only a single CSS is used instead, overwriting/ignoring others.

The issue is that Cascading Style Sheets don't 'cascade'.

[ggrossetie]

Hello,

I have reproduce the behavior of the stylesheet option in Asciidoctor:

$ asciidoctor -a stylesheet=mystyles.css mysample.adoc

In this case, mystyles.css will replace the default style. https://asciidoctor.org/docs/user-manual/#customizing-your-output

Having said that, it's also possible to add custom content to the head or footer of an output document using docinfo files with Asciidoctor.

We could probably load a docinfo from the options pages to add custom content:

<meta name="keywords" content="open source, documentation">
<style>
  h1 {
    color: #673ab7;
  }
</style>
<script>
  console.log('hello')
</script>

What do you think?

[mojavelinux]

@Mogztter I think what @WaterSibilantFalling is asking about is being able to use multiple stylesheets (either two custom ones, or one that builds on the default one).

[ggrossetie]

Yes I understand that but I was trying to find an existing feature in Asciidoctor to meet this requirement. With a "docinfo" you will still be able to select a built-in stylesheet or a custom one (ie. equivalent to the stylesheet option) and then provide additional styles in the docinfo. The nice thing about the "docinfo" is that it's not limited to styles (you can add <meta> tags or a script in the header or footer of the page).

But maybe it's far-fetched? If that's the case, then we could just allow to add additional stylesheets (that would be the equivalent of the proposed feature in Asciidoctor to define a comma separated list of stylesheets).

[mojavelinux]

When it comes to configuration for the preview, tools don't have to be limited by what core provides. In this case, you can allow multiple stylesheets to be specified and apply them to the preview. Another approach would be to allow the sole stylesheet to use the @import directive to import a series of stylesheets.

Although docinfo is powerful, using it to change styles to create a theme is not really its intended use. It's more for adding HTML and integrates to standalone documents.

[ggrossetie]

Another approach would be to allow the sole stylesheet to use the @import directive to import a series of stylesheets.

That is actually already possible (though not documented)

@import url("chrome-extension://eipehadpegdjlgkljfkaiielnfnebnlb/css/themes/asciidoctor.css");

h2 {
  color: #673ab7;
}

Please note that the URI is fixed (eipehadpegdjlgkljfkaiielnfnebnlb is actually a unique extension id) and all the themes available are: https://github.com/asciidoctor/asciidoctor-browser-extension/tree/master/app/css/themes

@WaterSibilantFalling is it an acceptable solution?

[WaterSibilantFalling]

@WaterSibilantFalling is it an acceptable solution?

Yes, it is. Thank you.

Though your CSS Cascading Style Sheets should cascade.. . .

[WaterSibilantFalling]

<meta name="keywords" content="open source, documentation">
<style>
  h1 {
    color: #673ab7;
  }
</style>
<script>
  console.log('hello')
</script>

I worked this out myself and tried it, but it didn't work, the bit.

the proposed feature in Asciidoctor to define a comma separated list of stylesheets

That's whats required

That is actually already possible (though not documented)

@import url("chrome-extension://eipehadpegdjlgkljfkaiielnfnebnlb/css/themes/asciidoctor.css");

h2 { color: #673ab7; }

I will try this, importing the existing asciidoctor style sheet, then using the @import you suggest, then inlining my CSS.

Nice if I could just apply a few CSS files, on top of the default.

[WaterSibilantFalling]

all the themes available are: https://github.com/asciidoctor/asciidoctor-browser-extension/tree/master/app/css/themes

If I can use these on the command line, then I can just cascade (i.e. concatenate) the files myself ....

.... though having it in the browser is extra-great, for a number of reasons (like other browser plugins to assist the editing experience, printer support)

[mojavelinux]

Though your CSS Cascading Style Sheets should cascade.. . .

Our sylesheets do cascade, so I don't know why you keep saying this. What Asciidoctor allows you to do is replace the stylesheet (meaning start from a clean slate). (Otherwise, you'd always have to override what the built-in stylesheet provides). Using that feature, you can combine your stylesheets however you want (using @import) and they will natural cascade.

There's an open proposal in core to allow multiple stylesheets to be specified. Of course they'll cascade since that's how CSS works. https://github.com/asciidoctor/asciidoctor/issues/3471 Asciidoctor is not doing anything to prevent stylesheets from cascading.

[jhannwong]

Though your CSS Cascading Style Sheets should cascade.. . .

Our sylesheets do cascade, so I don't know why you keep saying this. What Asciidoctor allows you to do is replace the stylesheet (meaning start from a clean slate). (Otherwise, you'd always have to override what the built-in stylesheet provides). Using that feature, you can combine your stylesheets however you want (using @import) and they will natural cascade.

There's an open proposal in core to allow multiple stylesheets to be specified. Of course they'll cascade since that's how CSS works. asciidoctor/asciidoctor#3471 Asciidoctor is not doing anything to prevent stylesheets from cascading.

Actually, "Cascading Stylesheets" mean multiple CSS files, not just "cascading rules" (where later rules in the same file override earlier rules).

So, no, Asciidoctor doesn't do "Cascading Stylesheets". @WaterSibilantFalling is correct.

About the only way to truly have "Cascading Stylesheets" (not just "cascading style rules") is to use docinfo, which as you mentioned, isn't the correct tool for the job (it's meant for adding to the Model, not to the Style).

(Aside: I'm interested to help out. Is there any quick guide on the general structure of Asciidoctor, so I can start contributing quickly? If not, lemme know, and I'll endeavor to write up such a guide for future contributors.)

[mojavelinux]

So, no, Asciidoctor doesn't do "Cascading Stylesheets".

Sorry, that is not a correct assertion. As I have said earlier, Asciidoctor does do cascading stylesheets. To learn more about how Asciidoctor processes stylesheets and how to extend them, please see https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/ and https://docs.asciidoctor.org/asciidoctor/latest/html-backend/stylesheet-modes/ and https://docs.asciidoctor.org/asciidoctor/latest/html-backend/custom-stylesheet/

[ggrossetie]

I'm tempted to update the title to "Support multiple stylesheets" or "Allow to extend the built-in themes".