feat(postrenderer): add theme manifests

Author: iamgio

quarkdown-html/.gitignore

@@ -5,6 +5,7 @@ src/main/resources/render/script/quarkdown.js.map
 # Sass
 src/main/resources/render/theme/**/*.css
 src/main/resources/render/theme/**/*.css.map
+src/main/resources/render/theme/**/*.json
 
 # e2e
 src/test/e2e/**/output/

quarkdown-html/build.gradle.kts

@@ -22,19 +22,21 @@ dependencies {
     implementation("org.jetbrains.kotlinx:kotlinx-serialization-json:1.10.0")
 }
 
-// Third-party library bundling
-//
-// Libraries from node_modules are copied into src/main/resources/render/lib/
-// at Gradle build time, so they are bundled in the JAR and copied to the
-// Quarkdown output directory at compilation time.
-//
-// A nested third-party-manifest.json is generated at the end so that the
-// Kotlin runtime can enumerate JAR resources (JAR directories are not listable).
-//
-// To add a new library:
-// 1. Add the npm package to package.json
-// 2. Add a LibrarySpec entry to `librariesToBundle`
-// 3. Add a ThirdPartyLibrary subclass in ThirdPartyLibrary.kt
+/*
+Third-party library bundling
+
+Libraries from node_modules are copied into src/main/resources/render/lib/
+at Gradle build time, so they are bundled in the JAR and copied to the
+Quarkdown output directory at compilation time.
+
+A nested third-party-manifest.json is generated at the end so that the
+Kotlin runtime can enumerate JAR resources (JAR directories are not listable).
+
+To add a new library:
+1. Add the npm package to package.json
+2. Add a LibrarySpec entry to `librariesToBundle` (or to `fontsourcePackages` for fonts)
+3. For non-font libraries, add a ThirdPartyLibrary subclass in ThirdPartyLibrary.kt
+*/
 
 val libDir = projectDir.resolve("src/main/resources/render/lib")
 val nodeModules = projectDir.resolve("node_modules")
@@ -70,16 +72,12 @@ val librariesToBundle =
     )
 
 /**
- * @fontsource font sets, keyed by layout theme name.
- * Each entry lists the @fontsource package names to include.
- * All latin-subset woff2 variants are auto-discovered from each package's `files/` directory,
- * and `@font-face` declarations are derived from the `{font}-latin-{weight}-{style}.woff2` naming convention.
+ * @fontsource packages to bundle. Each is placed in its own `lib/fonts/{name}/` directory
+ * with auto-discovered latin woff2 variants and a generated `fonts.css`.
+ * SCSS layout themes select which fonts they need via `@import url(...)`.
  */
-val fontsourceSets =
-    mapOf(
-        "fonts/minimal" to listOf("lato", "inter", "noto-sans-mono"),
-        "fonts/beamer" to listOf("source-sans-pro", "fira-sans", "noto-sans-mono"),
-    )
+val fontsourcePackages =
+    listOf("lato", "inter", "noto-sans-mono", "source-sans-pro", "fira-sans")
 
 /**
  * Highlight.js theme CSS files to copy as SCSS partials for compile-time inlining into color themes.
@@ -137,8 +135,8 @@ val bundleThirdParty =
                 }
             }
 
-            fontsourceSets.forEach { (targetSubdir, fontNames) ->
-                bundleFontsource(targetSubdir, fontNames)
+            fontsourcePackages.forEach { fontName ->
+                bundleFontsource("fonts/$fontName", listOf(fontName))
             }
 
             scssThirdParty.mkdirs()
@@ -174,7 +172,8 @@ fun bundleFontsource(
         val filesDir = nodeModules.resolve("@fontsource/$fontName/files")
         val family = fontName.split("-").joinToString(" ") { it.replaceFirstChar(Char::uppercaseChar) }
 
-        filesDir.listFiles()
+        filesDir
+            .listFiles()
             ?.filter { it.name.startsWith("$fontName-latin-") && it.extension == "woff2" }
             ?.sortedBy { it.name }
             ?.forEach { sourceFile ->
@@ -203,74 +202,61 @@ fun bundleFontsource(
 }
 
 /**
- * Generates `third-party-manifest.json` with one top-level key per library.
- *
- * Each key maps to a nested JSON tree of that library's internal directory structure,
- * with files at each level listed under `_files`:
+ * Generates `third-party-manifest.json` as a nested JSON tree mirroring the `lib/` directory structure.
+ * Files at each level are listed under `_files`; subdirectories become nested objects.
  *
  * ```json
  * {
  *   "katex": {
  *     "_files": ["katex.min.css", "katex.min.js"],
  *     "fonts": { "_files": ["KaTeX_Main-Regular.woff2"] }
  *   },
- *   "fonts/latex": {
- *     "_files": ["fonts.css", "ComputerModern-Serif-Regular.woff"]
+ *   "fonts": {
+ *     "latex": { "_files": ["fonts.css", "ComputerModern-Serif-Regular.woff"] }
  *   }
  * }
  * ```
- *
- * A directory that contains files is a library (e.g. `katex`). A directory that only contains
- * subdirectories is not a library itself; its children are explored recursively until a library
- * is found (e.g. `fonts/` has no files, so `fonts/latex` becomes a library entry).
- * This allows the Kotlin runtime to look up libraries by name without path traversal.
  */
 fun generateNestedManifest() {
     fun dirToJson(dir: File): Map<String, Any> =
         buildMap {
-            dir.listFiles()
-                ?.filter { it.isFile }
+            dir
+                .listFiles()
+                ?.filter { it.isFile && it.name != "third-party-manifest.json" }
                 ?.map { it.name }
                 ?.sorted()
                 ?.takeIf { it.isNotEmpty() }
                 ?.let { put("_files", it) }
 
-            dir.listFiles()
+            dir
+                .listFiles()
                 ?.filter { it.isDirectory }
                 ?.sortedBy { it.name }
                 ?.forEach { put(it.name, dirToJson(it)) }
         }
 
-    val manifest = linkedMapOf<String, Any>()
-
-    fun collectLibraries(dir: File, prefix: String) {
-        dir.listFiles()
-            ?.filter { it.isDirectory }
-            ?.sortedBy { it.name }
-            ?.forEach { child ->
-                val key = if (prefix.isEmpty()) child.name else "$prefix/${child.name}"
-                val hasFiles = child.listFiles()?.any { it.isFile } ?: false
-
-                if (hasFiles) {
-                    manifest[key] = dirToJson(child)
-                } else {
-                    collectLibraries(child, key)
-                }
-            }
-    }
-
-    collectLibraries(libDir, "")
-
-    libDir.resolve("third-party-manifest.json")
-        .writeText(JsonOutput.prettyPrint(JsonOutput.toJson(manifest)))
+    libDir
+        .resolve("third-party-manifest.json")
+        .writeText(JsonOutput.prettyPrint(JsonOutput.toJson(dirToJson(libDir))))
 }
 
 // SCSS and TypeScript bundling
 
+val scssDir = projectDir.resolve("src/main/scss")
+val themeOutputDir = projectDir.resolve("src/main/resources/render/theme")
+
 tasks.compileSass {
-    sourceDir = projectDir.resolve("src/main/scss")
-    outputDir = projectDir.resolve("src/main/resources/render/theme")
+    sourceDir = scssDir
+    outputDir = themeOutputDir
     dependsOn(bundleThirdParty) // hljs SCSS partials must be copied before SASS compilation
+
+    // Copy layout theme JSON manifests (font dependencies) alongside the compiled CSS.
+    doLast {
+        copy {
+            from(scssDir.resolve("layout")) { include("*.json") }
+            into(themeOutputDir.resolve("layout"))
+        }
+    }
 }
 
 val bundleTypeScript =

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/post/HtmlOnlyPostRenderer.kt

@@ -1,7 +1,6 @@
 package com.quarkdown.rendering.html.post
 
 import com.quarkdown.core.context.Context
-import com.quarkdown.core.document.DocumentTheme
 import com.quarkdown.core.media.storage.options.MediaStorageOptions
 import com.quarkdown.core.media.storage.options.ReadOnlyMediaStorageOptions
 import com.quarkdown.core.pipeline.output.ArtifactType
@@ -24,13 +23,11 @@ import com.quarkdown.rendering.html.post.document.HtmlDocumentBuilder
  * @param name the name of the HTML output resource, without extension
  * @param relativePathToRoot the relative path to follow to get from the HTML resources generated by this post-renderer
  *                           to the root (the location where the main HTML file is located, alongside `script`, `theme`, etc.)
- * @param theme the active document theme, forwarded to [HtmlDocumentBuilder] for third-party library resolution
  */
 class HtmlOnlyPostRenderer(
     private val context: Context,
     private val name: String = "index",
     private val relativePathToRoot: String,
-    private val theme: DocumentTheme,
 ) : PostRenderer {
     // HTML requires local media to be resolved from the file system.
     override val preferredMediaStorageOptions: MediaStorageOptions =
@@ -40,7 +37,6 @@ class HtmlOnlyPostRenderer(
         HtmlDocumentBuilder(
             context,
             relativePathToRoot,
-            theme = theme,
             sidebarContent = SidebarRenderer.render(context),
         ).build(content)
 

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/post/HtmlPostRenderer.kt

@@ -42,7 +42,6 @@ class HtmlPostRenderer(
         HtmlOnlyPostRenderer(
             context,
             relativePathToRoot = relativePathToRoot,
-            theme = theme,
         ),
     private val resourcesProvider: () -> Set<PostRendererResource> =
         {
@@ -52,10 +51,7 @@ class HtmlPostRenderer(
                     locale = context.documentInfo.locale,
                 ),
                 ScriptPostRendererResource(),
-                ThirdPartyPostRendererResource(
-                    context = context,
-                    theme = theme,
-                ),
+                ThirdPartyPostRendererResource(context, layoutTheme = theme.layout),
                 MediaPostRendererResource(context.mediaStorage),
                 if (context.documentInfo.type == DocumentType.DOCS) {
                     SearchIndexPostRendererResource(SearchIndexGenerator.generate(context.sharedSubdocumentsData))

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/post/document/HtmlDocumentBuilder.kt

@@ -1,7 +1,6 @@
 package com.quarkdown.rendering.html.post.document
 
 import com.quarkdown.core.context.Context
-import com.quarkdown.core.document.DocumentTheme
 import com.quarkdown.core.document.DocumentType
 import com.quarkdown.rendering.html.post.thirdparty.HeadContribution
 import com.quarkdown.rendering.html.post.thirdparty.ThirdPartyLibrary
@@ -38,13 +37,11 @@ import kotlinx.html.unsafe
  * @param context the rendering context containing document metadata, attributes, and configuration
  * @param relativePathToRoot the relative path from the current document to the root directory,
  *                           used to correctly reference shared resources (scripts, themes, etc.)
- * @param theme the active document theme, used to resolve which third-party libraries to include
  * @param sidebarContent the pre-rendered sidebar HTML content (table of contents)
  */
 class HtmlDocumentBuilder(
     private val context: Context,
     private val relativePathToRoot: String,
-    private val theme: DocumentTheme,
     private val sidebarContent: CharSequence,
 ) {
     private val document = context.documentInfo
@@ -132,7 +129,7 @@ class HtmlDocumentBuilder(
      */
     private fun HEAD.thirdPartyLibraries() {
         ThirdPartyLibrary
-            .all(theme)
+            .all()
             .filter { it.isRequired(context) }
             .forEach { library ->
                 library.headContributions.forEach { contribution ->

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/post/resources/LayoutThemeManifest.kt

@@ -0,0 +1,47 @@
+package com.quarkdown.rendering.html.post.resources
+
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.Json
+
+/**
+ * Resolves resource requirements declared by a layout theme's JSON manifest.
+ *
+ * Each layout theme may declare its dependencies in a JSON manifest file
+ * at `/render/theme/layout/{layoutName}.json`, for example:
+ * ```json
+ * {"fonts": ["fonts/lato", "fonts/inter"]}
+ * ```
+ *
+ * Font names correspond to keys in `third-party-manifest.json` and to directories
+ * under `lib/` in the output. SCSS layout themes reference these fonts via `@import url()`,
+ * and this class ensures the corresponding files are bundled in the output.
+ *
+ * @param fonts third-party font library names required by this layout theme
+ */
+@Serializable
+data class LayoutThemeManifest(
+    val fonts: List<String> = emptyList(),
+) {
+    companion object {
+        private val cache = mutableMapOf<String, LayoutThemeManifest?>()
+
+        /**
+         * Loads the manifest for the given [layoutName],
+         * or `null` if the layout has no manifest. Results are cached by name.
+         */
+        fun load(layoutName: String?): LayoutThemeManifest? {
+            if (layoutName == null) return null
+            return cache.getOrPut(layoutName) { parse(layoutName) }
+        }
+
+        private fun parse(layoutName: String): LayoutThemeManifest? {
+            val json =
+                LayoutThemeManifest::class.java
+                    .getResource("/render/theme/layout/$layoutName.json")
+                    ?.readText()
+                    ?: return null
+
+            return Json.decodeFromString<LayoutThemeManifest>(json)
+        }
+    }
+}

quarkdown-html/src/main/kotlin/com/quarkdown/rendering/html/post/resources/ThirdPartyPostRendererResource.kt

@@ -1,37 +1,39 @@
 package com.quarkdown.rendering.html.post.resources
 
 import com.quarkdown.core.context.Context
-import com.quarkdown.core.document.DocumentTheme
 import com.quarkdown.core.pipeline.output.OutputResource
 import com.quarkdown.rendering.html.post.thirdparty.ThirdPartyLibrary
 
 /**
  * A [PostRendererResource] that bundles third-party libraries (scripts, styles, fonts) into the output,
  * enabling fully offline HTML rendering without any CDN dependencies.
  *
- * Library inclusion is driven entirely by [ThirdPartyLibrary], the single source of truth
- * for each library's condition and identity. This class simply filters the required libraries
- * and delegates file loading to [ThirdPartyResourceLoader].
+ * Library inclusion is driven by [ThirdPartyLibrary] for scripts and styles,
+ * and by [LayoutThemeManifest] for font libraries declared by the active layout theme.
+ * File loading is delegated to [ThirdPartyResourceLoader].
  *
  * @param context the rendering context, used to evaluate library inclusion conditions
- * @param theme the active document theme, used to determine which font libraries to include
+ * @param layoutTheme the active layout theme name, used to resolve font dependencies
  */
 class ThirdPartyPostRendererResource(
     private val context: Context,
-    private val theme: DocumentTheme,
+    private val layoutTheme: String?,
 ) : PostRendererResource {
     override fun includeTo(
         resources: MutableSet<OutputResource>,
         rendered: CharSequence,
     ) {
-        val requiredNames =
+        val libraryNames =
             ThirdPartyLibrary
-                .all(theme)
+                .all()
                 .filter { it.isRequired(context) }
                 .map { it.name }
 
-        if (requiredNames.isEmpty()) return
+        val fontNames = LayoutThemeManifest.load(layoutTheme)?.fonts.orEmpty()
 
-        resources += ThirdPartyResourceLoader.loadAll("lib", requiredNames)
+        val allNames = libraryNames + fontNames
+        if (allNames.isEmpty()) return
+
+        resources += ThirdPartyResourceLoader.loadAll("lib", allNames)
     }
 }