Adding a dedicated stylesheet to the page layout

[samueleresca]

Adding a dedicated stylesheet option to the page layout to support dedicated styling for pages.

[pjfanning]

I don't quite get how this works. There is already material.custom.stylesheet. So far, the only examples I have seen of these props being set - sets them for the whole build. I'm not sure how they can be set on a per page basis.
What if page.properties has both stylesheet properties set - won't that lead to 2 <link rel="stylesheet" entries?

I still have a big preference for #84 and gutting this project. It is far too complicated to vote on pekko-sbt-paradox releases and then have to uptake the releases in so many places.

[samueleresca]

I don't quite get how this works. There is already material.custom.stylesheet. So far, the only examples I have seen of these props being set - sets them for the whole build. I'm not sure how they can be set on a per page basis. What if page.properties has both stylesheet properties set - won't that lead to 2 <link rel="stylesheet" entries?

I still have a big preference for #84 and gutting this project. It is far too complicated to vote on pekko-sbt-paradox releases and then have to uptake the releases in so many places.

These props can be set also at markdown level using the following approach:

---
material.custom.stylesheet: ../assets/stylesheet/style.css
---

## Apache Pekko

In case of the home we will have 2 <link rel="stylesheet" enties:

1. One referring to the pekko-theme.css style (common to all docs pages)
2. One referring to the home.css style (dedicated to the home)

That said, I agree that we need a more sustainable way of updating the static assets. I'm proceeding by commenting #84 with the next steps.

[pjfanning]

Thanks, I wasn't aware that you can set properties that way (in the markdown file itself).

With that approach, do we need material.custom.page-stylesheet ? I'm still concerned that can end up with 2 <link rel="stylesheet" entries in the HTML.

[samueleresca]

Thanks, I wasn't aware that you can set properties that way (in the markdown file itself).

With that approach, do we need material.custom.page-stylesheet ? I'm still concerned that can end up with 2 <link rel="stylesheet" entries in the HTML.

Yes, we gonna end up with +1 <link rel="stylesheet" in the HTML. At the moment, the page is rendered as:

...
<meta name="description" content="incubator-pekko-site">
<link rel="shortcut icon" href="assets/images/pekko_favicon.png">
<title>Apache Pekko</title>
<link rel="stylesheet" href="assets/stylesheets/application.451f80e5.css">
<link rel="stylesheet" href="assets/stylesheets/application-palette.22915126.css">
<link rel="stylesheet" href="lib/material__tabs/dist/mdc.tabs.min.css">
<link rel="stylesheet" href="lib/prettify/prettify.css">
<script src="assets/javascripts/modernizr.1aa3b519.js"></script>
<link rel="stylesheet" href="assets/fonts/font-awesome.css">
<link rel="stylesheet" href="assets/fonts/material-icons.css">
<link rel="stylesheet" href="assets/stylesheets/paradox-material-theme.css">
<link rel="stylesheet" href="assets/stylesheets/pekko-theme.css">
</head>
...

This change, in combination with a home.md specifying the following:

---
material.custom.page-stylesheet: ../assets/stylesheet/home.css
---

## Apache Pekko

The rendered result will be:

...
<meta name="description" content="incubator-pekko-site">
<link rel="shortcut icon" href="assets/images/pekko_favicon.png">
<title>Apache Pekko</title>
<link rel="stylesheet" href="assets/stylesheets/application.451f80e5.css">
<link rel="stylesheet" href="assets/stylesheets/application-palette.22915126.css">
<link rel="stylesheet" href="lib/material__tabs/dist/mdc.tabs.min.css">
<link rel="stylesheet" href="lib/prettify/prettify.css">
<script src="assets/javascripts/modernizr.1aa3b519.js"></script>
<link rel="stylesheet" href="assets/fonts/font-awesome.css">
<link rel="stylesheet" href="assets/fonts/material-icons.css">
<link rel="stylesheet" href="assets/stylesheets/paradox-material-theme.css">
<link rel="stylesheet" href="assets/stylesheets/pekko-theme.css">
<link rel="stylesheet" href="assets/stylesheet/home.css">
...

This would allow us to keep the pekko-theme.css as a common stylesheet for common elements such as footer,header, nav bar.
On top of that, we can optionally specify a <page_name>.css to be used for styles specific to a page i.e.: homepage

This approach might be benefcial because:

• you keep styling across pages in pekko-theme.css
• <page>.css for page-related sytling
• Avoid duplication between pekko-theme.css and page.css styles.
• Avoid to override a layout everytime you need page-specific style, see: https://github.com/apache/incubator-pekko-site/pull/47/files#diff-466bb92234fde71107d802b3aee2a64ecd1c40ec841da5176623f88f9d6a9f11R1

[pjfanning]

Thanks for the explanation. Change makes sense.