Closed hendrikebbers closed 2 years ago
Hi, this week i'd love to to work on this issue ;)
@MBoegers cool :)
Asciidoctor provides multiple ways to include/provide CSS to our adoc files. They can be configured:
:stylesheet:
and :stylesdir:
-a stylesheet
and -a stylesdir
Asciidoctor provides different ways to combine HTML with CSS. Its is possible to:
link
attribute
-a linkcss
style
attribute
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.
Personally I would configure the styles at the build via cli and stick with Asciidoctors default embedded <styles>
behavior.
@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?
@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
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
🆕🐥 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 (seebuild.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.
🎉 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.