diff --git a/README.md b/README.md index 1ceae95c5..9cc3451c0 100644 --- a/README.md +++ b/README.md @@ -4300,24 +4300,19 @@ layer. For example, let's say you are fighting with a third party library whose styles are a bit too aggressive and are interfering with your own styles. -First, inside your build script, import the stylesheet using -an [`@import` directive](https://developer.mozilla.org/en-US/docs/Web/CSS/@import): +First, inside your build script, import the stylesheet using Kobweb's `importCss` function, which internally uses the +CSS [`@import` at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@import): ```kotlin // BEFORE kobweb.app.index.head.add { - link { - rel = "stylesheet" - href = "/highlight.js/styles/dracula.css" - } + link(href = "/highlight.js/styles/dracula.css", rel = "stylesheet") } // AFTER kobweb.app.index.head.add { style { - unsafe { - raw("@import url(\"/highlight.js/styles/dracula.css\") layer(highlightjs);") - } + importCss("/highlight.js/styles/dracula.css", layerName = "highlightjs") } } ``` diff --git a/tools/gradle-plugins/core/src/main/kotlin/com/varabyte/kobweb/gradle/core/util/HtmlUtil.kt b/tools/gradle-plugins/core/src/main/kotlin/com/varabyte/kobweb/gradle/core/util/HtmlUtil.kt index 207102137..2225d8cc4 100644 --- a/tools/gradle-plugins/core/src/main/kotlin/com/varabyte/kobweb/gradle/core/util/HtmlUtil.kt +++ b/tools/gradle-plugins/core/src/main/kotlin/com/varabyte/kobweb/gradle/core/util/HtmlUtil.kt @@ -1,8 +1,10 @@ package com.varabyte.kobweb.gradle.core.util import kotlinx.html.HEAD +import kotlinx.html.STYLE import kotlinx.html.TagConsumer import kotlinx.html.stream.createHTML +import kotlinx.html.unsafe object HtmlUtil { // Workaround for generating child nodes without the containing tag @@ -23,3 +25,41 @@ object HtmlUtil { fun serializeHeadContents(block: HEAD.() -> Unit): String = createHTML(prettyPrint = false, xhtmlCompatible = true).headFragment(block) } + +/** + * Adds an [`@import`](https://developer.mozilla.org/en-US/docs/Web/CSS/@import) rule to import a CSS stylesheet, + * optionally loading it into a specific [CSS Cascade layer](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Cascade_layers). + * + * This can be useful when using a third party CSS library whose styles are a bit too aggressive and are interfering + * with your own styles. + * + * For example, replace a `` tag with an `@import` rule: + * + * ``` + * kobweb.app.index.head.add { + * // Before + * link(href = "/highlight.js/styles/dracula.css", rel = "stylesheet") + * // After + * style { + * importCss("/highlight.js/styles/dracula.css", layerName = "highlightjs") + * } + * } + * ``` + * + * Then, register your new layer in an `@InitSilk` block: + * + * ``` + * @InitSilk + * fun initSilk(ctx: InitSilkContext) { + * // Layer(s) referenced in build.gradle.kts + * ctx.stylesheet.cssLayers.add("highlightjs", after = SilkLayer.BASE) + * } + * ``` + * + * @param url The URL of the CSS file to import. This can be an external URL or a path to a local `public` resource. + * @param layerName The cascade layer in which to load the stylesheet. **For this to have any effect, the layer + * MUST be registered in an `@InitSilk` block.** + */ +fun STYLE.importCss(url: String, layerName: String? = null) { + unsafe { raw("@import url(\"$url\")${if (layerName != null) " layer($layerName)" else ""};\n") } +}