Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Jul 7, 2024

Conversation

jenshalm
Copy link
Contributor

@jenshalm jenshalm commented Jul 2, 2024

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

@jenshalm jenshalm added this to the 1.2.0 milestone Jul 2, 2024
@noelwelsh
Copy link

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

@jenshalm jenshalm merged commit 4cade29 into main Jul 7, 2024
21 checks passed
@jenshalm jenshalm deleted the theme/includes branch July 15, 2024 12:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants