Find the best way to introduce css stylesheets

[hendrikebbers]

🆕🐥 First Timers Only

This issue is reserved for people who never contributed to Open Source before. We know that the process of creating a pull request is the biggest barrier for new contributors. This issue is for you 💝

👾 Description of the issue

The PR https://github.com/AdoptOpenJDK/website-adoptium-documentation/pull/13 introduced custom style classes for the documentation. To support such classes a new css file needs to be added. Asciidoc provides different ways how such CSS file can be loaded. Some documentation can be found here:

https://docs.asciidoctor.org/asciidoc/latest/text/custom-inline-styles/ https://docs.asciidoctor.org/asciidoctor/latest/html-backend/default-stylesheet/#customize-extend https://docs.asciidoctor.org/asciidoctor/latest/html-backend/custom-stylesheet/

Currently the new style sheet is defined directly on the asciidoc files and internally does an css import to include the original asciidoc stylesheet. We need to check if this is the best way to do it or if we better add such informational parameters to the asciidoctor command (see build.sh file).

As a result this issue should provide a short overview of the different possibilities and their benefits. Based on a simple discussion in this issue a PullRequest with the best possibility should be provided.

📋 Step by Step

To solve this issue and contribute a fix you should check the following step-by-step list. A more detailed documentation of the workflow can be found here.

• [ ] Claim this issue: Comment below.
• [ ] Fork the repository in github by simply clicking the 'fork' button.
• [ ] Check out the forked repository
• [ ] Create a feature branch for the issue. We do not have any naming definition for branches.
• [ ] Commit your changes.
• [ ] Start a Pull Request.
• [ ] Done 👍 Ask in comments for a review :)
• [ ] If the reviewer find some missing peaces or a problem he will start a discussion with you and describe the next steps how the problem can be solved.
• [ ] You did it 🎉 We will merge the fix in the master branch.
• [ ] Thanks, thanks, thanks for being part of this project as an open source contributor ❤️

🎉 Contribute to Hacktoberfest

Solve this issue as part of the Hacktoberfest event and get a change to receive cool goodies like a T-Shirt. 🎽

🤔❓ Questions

If you have any questions just ask us directly in this issue by adding a comment. You can join our community chat at Slack. Next to this you can find a general manual about open source contributions here.

[MBoegers]

Hi, this week i'd love to to work on this issue ;)

[hendrikebbers]

@MBoegers cool :)

[MBoegers]

CSS and Asciidoctor

Configure stylesheets

Asciidoctor provides multiple ways to include/provide CSS to our adoc files. They can be configured:

1. Within each adoc file
   • tag would be :stylesheet: and :stylesdir:
2. For each build as parameter
   • flags would be -a stylesheet and -a stylesdir

HTML result

Asciidoctor provides different ways to combine HTML with CSS. Its is possible to:

1. Link CSS files within HTML headers link attribute
   • cli flag is -a linkcss
2. Include CSS into HTML header via style attribute
   • this is default behavior

Conclusion

Defining the stylesheets within the adoc files is dangerous. One could forget or include a type, as result the site would render differently. Therefore, linking at build time via the cli seems to be the pragmatic way.

Embedding the styles within a styles tag increases the size of the HTML file to download. Including the stylesheet via <link> could enable caching and slightly boost the loading time within modern browsers. But linking while having nested sites becomes tricky because the paths are different for each site, see Asciidoctor.

My opinion

Personally I would configure the styles at the build via cli and stick with Asciidoctors default embedded <styles> behavior.

[hendrikebbers]

@MBoegers sounds good. I like to link the style at render-time, too. At the end we might use JAsciiDoctor to render the files. We need to check if the functionality can be achieved with the Java lib, too. Since we do not need an embedded catalog of all pages in the doc we maybe can call the rendering process for each adoc-file individually and take care of the css path by doing so?

[MBoegers]

@hendrikebbers yes, if we invoke the translation on every file, it should be possible to handle the path correctly.

JAsciiDoctor is just Java-API for Asciidoctor CLI running on JRuby. It supports all features that the CLI has. The Examples show how easy it is to set CLI options with Java. The used Attributes#builder class supports the CSS-Attributes as well, see

[hendrikebbers]

Ok, sounds like a good solution so far :) I really need to find some time to finalise #13 ;) Once this is done we can extract the custom css classes and try to change the GitHub action by using that approach