Loading custom JS and CSS in non-Helium themes

[noelwelsh]

The PR for changing how CSS and JS is included only refers to the Helium theme. There is no mention of other themes, and the implication is that other themes do not support this functionality.

If custom CSS and JS can no longer be loaded without using the Helium theme, this seems to mean that other themes are now effectively useless. If this is the case I think you should just get rid of Theme as I cannot see it serves any purpose. If this is not the case, loading CSS and JS without using Helium should be documented.

[jenshalm]

@noelwelsh I converted this to a discussion as I am not entirely clear what your exact scenario is and what concrete improvement can be made. If we can distill something actionable out of this discussion I am happy to create a new, more narrowly focused issue for it. Pinging you directly as I'm not sure GitHub keeps you subscribed to this discussion after conversion.

The Theme AP is actually an API for library authors and not for end users. The "Creating Themes" chapter in the manual explains this in the opening section. In that context features like linking styles are not provided for other themes, it is something potentially provided by other themes. If your use case is not to publish a reusable theme for other users, but merely "I want to create a site without using the Helium theme" this is a completely different scenario where you don't need the Theme API so I'll briefly cover all 3 use cases below.

A) Publishing a reusable theme for other users

Generators which are more popular than Laika often come with a lot of 3rd party themes published by other authors. This is its main purpose, an API that allows to bundle typical functionality provided by themes and publish it as a library. It's just that for Laika I'm not aware that this has ever happened and with the decline of interest in Scala it might very well never happen. Other themes would also come with their own, specific configuration API and the inclusion of styles by the end users of the theme would be part of that API. Since I have zero feedback for this use case, I would not be surprised if some aspects of creating a reusable theme are unclear or inconvenient and I'm happy to consider adding functionality or documentation based on feedback, but I somehow suspect this is not actually your use case.

B) Extending existing themes

The second purpose of the theme API is to allow to extend an existing theme via ThemeProvider.extendWith(ThemeProvider). Depending on the type of functionality of the extension, it would either add new functionality or override existing features of the base theme. One example of a library using this feature is the sbt-typelevel-site plugin which adjusts the Helium theme for Typelevel projects. Linking styles does not need to be discussed here, as such an extension can simply piggy-back on the configuration API of the host theme.

C) Creating a site without the Helium theme

The third scenario is that of an end user who simply wants to create a site without using the Helium theme, but with no intention to publish or reuse it. Here the Theme API can be used, but it's not really necessary and not the the main intended use case. You can often just easily install Theme.empty and build everything with core features. This does not mean that the API is redundant though as it's essential for the other two scenarios above, which means it's really impossible to remove it. Since this scenario also forces you to include your own custom template, you would usually not need the full set of options for linking styles as provided by the Helium API as you have just one specific use case. In the most basic scenario you could probably even simply hard-code those tags in that template. If you need more flexibility you can add that based on features shown in Creating Templates.

The sole reason that Helium has such a rich API for linking styles and JavaScript is that in previous versions the options were so limited that many users had to create a custom template for this one reason alone, to amend the link tags in the head section. But having a template that is an amended copy of the theme's default template is error-prone and inconvenient. Whenever the library publishes an update, you'd need to merge any changes into your copy or otherwise it gets out of sync and eventually even stops working properly as it does no longer match the underlying implementation. This happened in practice and was confusing for users and increasing the support burden for maintainers.

If you are creating your own template anyway, you don't have that issue and can simply do whatever you want inside your own templating solution.

Another reason that linking styles is not supported by core is that core also does not have any default templates, and ultimately this functionality has to be rendered into templates at some point, so it's a bit of a chicken-and-egg scenario.

I hope this might clear up a few things. If, based on these explanations, you have some concrete suggestions what we should improve, let me know.

[noelwelsh]

The issue I had is one of how the documentation presents the changes in functionality. In 1.0 linkCSS etc no longer work outside of Helium. The natural step is to read the Migration Guide, which links to a PR that exclusively talks about Helium. I came away from this with the impression that this functionality no longer existed outside of Helium. It was only later, reading the Theme documentation and the Helium code, that I found what I needed.

My use case is C) above. WIP is at https://github.com/creativescala/creative-scala-theme

[jenshalm]

Thanks for confirming. I have now at least added a quick pointer to the migration guide as part of #582 - basically suggesting the same thing as I did above: potentially hardcoding inclusions in the custom template or otherwise looking at more flexible features described in "Creating Templates".

Your WIP still refers to the Helium directives, but I'm not sure whether this is temporary or whether you intend to port them? In any case I felt that this level of flexibility is usually not required for producing a single site?

[noelwelsh]

I think it's fine. The problem I had is entirely with how the documentation presents the change.