typelevel / Laika

Site and E-book Generator and Customizable Text Markup Transformer for sbt, Scala and Scala.js
https://typelevel.org/Laika/
Apache License 2.0
414 stars 45 forks source link

promote most internals of Helium's include directive to public API in laika.theme.* #621

Closed jenshalm closed 3 months ago

jenshalm commented 3 months ago

Previously the @:includeJS and @:includeCSS directives were only available within the Helium theme, since they cannot be configured via HOCON like most other directives which come bundled with laika.core (some of the API allows to pass a function argument which cannot be encoded in HOCON).

For this reason authors of alternative themes or end users not using Helium had to either hard-code the includes into their custom templates or re-build or copy a lot of the implementation details.

Since the directives themselves cannot be promoted to become core directives for the reasons stated above, this PR simply aims to remove about 90% of the boilerplate required to re-create them outside of Helium by promoting their builder APIs from an internal Helium package to the public laika.theme.config package.

Example for creating an instance of a @:includeCSS directive that includes all CSS documents in the styles directory:

val config = IncludeCSSConfig.empty.internalCSS(Root / "styles")
val includeDirective = IncludeDirective.forCSS(htmlConfig = config)

This instance can then be registered like any other directive:

object MyDirectives extends DirectiveRegistry {
  val spanDirectives = Seq()
  val blockDirectives = Seq()
  val templateDirectives = Seq(includeDirective)
  val linkDirectives = Seq()
}

After this step the @:includeCSS directive can be used in any template outside of Helium.

There are no new tests since Helium now delegate to the promoted API, meaning the directive is tested within the Helium suites.

Proper documentation will be added to the manual as part of #576.

FYI @noelwelsh

noelwelsh commented 3 months ago

This looks great! It's going to save me a lot of work. Thanks!