Document how to specify custom styles

[mojavelinux]

Document how to change the styling with a custom stylesheet.

Changing the style and layout of the EPUB output is as simple as customizing the stylesheet. In fact, an EPUB is really just a webpage. Copy the the CSS from this repository into a local directory (e.g., epub3-styles) and pass the following flag:

-a epub3-stylesdir=epub3-styles

By default it will look for the following two files:

• epub3.css
• epub3-css3-only.css

The second file can be empty, but gives you the opportunity to add styles that are only understood by CSS3-compliant readers (anything based on Webkit).

[mojavelinux]

Link to this very useful primer about writing responsive styles for ebooks.

https://medium.com/@sandersk/responsive-ebook-design-a-primer-8bba01328219

[slonopotamus]

Nobody +1'ed or commented on this in more than 4 years. Either default style is really good or those who uses asciidoctor-epub3 just don't want custom styles. #182 indicates that users do use custom epub.css

[slonopotamus]

#336 also indicates that users want custom CSS, this time for pygments styles.

[hepabolu]

I too use custom css, basically the original files with a few tweaks. I just spent many hours figuring out what the tweaks were because I wanted to use the changes of alpha.18.

Is it possible to import the default files into my own custom css so I only have to override what is necessary?

[slonopotamus]

Currently, no, the only way is to replace the whole CSS with a custom one. But I've got some ideas on how this could be improved, it just needs a couple of hands to be implemented.

[hepabolu]

My Ruby knowledge is zero to none, but if there is another way I can help, let me know.

[slonopotamus]

Well, we could discuss how it could be implemented a bit. I imagine a simple solution that includes user-provided CSS file after builtin one.

[hepabolu]

Here's my proposal.

When I copied the epub3.css and epub3-css3-only.css files I noticed one of them had an import for epub3-fonts:

@import url("epub3-fonts.css");

which I didn't copy. But it was present in the final epub. Which to me proves the converter either copies the built-in files and overwrites them with the custom files or it follows the @import rules. And it also means that the ePub reader is able to include the @import files.

So my suggestion would be to rename the builtin css files and import them in the 'fixed' names. Something like this:

mv epub3.css builtin-epub3.css
mv epub3-css3-only.css builtin-epub3-css3-only.css

echo '@import url("builtin-epub3.css");' > epub3.css
echo '@import url("builtin-epub3-css3-only.css");' > epub3-css3-only.css

Whenever someone wants to override the builtin-css, they just copy the epub3* css files and add their customization under the @import line.

So the code needs to figure out which files to include into the final ePub.

I have no experience with a lot of ePub readers, just Apple Books and Kindle and a few ePub reader apps I downloaded from the App Store, so I'm not sure if this will be feasible for all ePub readers.

[slonopotamus]

I'm not very happy about parsing of user-created CSS. Doing that with regexes is fragile and pulling in some CSS parsing library might be a bit of an overkill. What we're currently doing with fonts is very ad-hoc and only works because we control contents of font CSS.

I think this logic also covers same cases:

1. If user provides CSS file that has the same name as builtin one, builtin is not included
2. If user provides a file named as user-<builtin>.css, builtin one is included and user file is included after builtin one

Also, how does theming work for Asciidoctor HTML backend?

[mojavelinux]

The HTML converter accepts a single stylesheet, via the stylesheet attribute, that replaces the one provided.

What you may be interested in copying is how Asciidoctor PDF handles fonts. You can specify multiple font paths. The font files are then resolved relative to those paths. If the name matches a built-in font, and the built-in font directory is in the list of font paths, the built-in one is used. See https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#configuring-the-font-search-path

In other words, you can specify multiple stylesheets and multiple stylesheet paths. If the stylesheets are specified, the user is expected to declare all of them. Though some of them can result to a built-in name.

[hepabolu]

I like the suggestion of overriding the built in stylesheets through a fixed set of steps.

However, if possible I would prefer to not use the Asciidoctor PDF version of declaring it all in a YAML file. I tried to theme the PDF version of the book but I ran into issues where I got all kinds of unexpected results (overrides not working and such). That may be caused entirely by my lack of understanding how it works under the hood, even though I am accustomed to using yaml.
So I gave up and just changed the font and the font color of the headers.

[mojavelinux]

if possible I would prefer to not use the Asciidoctor PDF version of declaring it all in a YAML file.

Sorry for the confusion. I was not suggesting the use of YAML. I was only trying to point out that Asciidoctor PDF implements a strategy that allows personal resources to be mixed with built-in resources.

[mojavelinux]

(Though I will say that the way the theme works in Asciidoctor PDF 2 is now much smoother. But that's a separate matter).

[hepabolu]

Ok, is that version out? Sounds like a good idea to try, if it is.

[mojavelinux]

Please follow this milestone for status on the release: https://github.com/asciidoctor/asciidoctor-pdf/milestone/30 (we shouldn't be discussing it here)

[slonopotamus]

I am going to implement @hepabolu proposal (#43 (comment)), unless someone has a better idea.

1. We rename all builtin CSS files to builtin-<name>.css and always bundle them in epub
2. We bundle user-provided <name>.css if it exists. Otherwise, we bundle generated <name>.css that says @import url("builtin-<name>.css");

So:

If user wants default styles, they do nothing.

If user wants to adjust builtin styles, they provide a CSS file that imports builtin one and contains user-provided CSS rules.

And finally, if user wants totally custom styles, they provide a CSS file that does not include builtin one. In this case we will bundle builtin CSS into epub anyway, though.