feat(build): load html libs from install layout

Author: iamgio

build.gradle.kts

@@ -129,6 +129,12 @@ distributions.main {
                 include("*.qd")
             }
         }
+        // Third-party HTML library files (KaTeX, fonts, etc.) are bundled by the quarkdown-html module
+        // and placed in lib/html for filesystem-based loading at runtime.
+        val htmlModule = project(":quarkdown-html")
+        into("lib/html") {
+            from(htmlModule.layout.buildDirectory.dir("thirdparty"))
+        }
         // Include the generated Dokka documentation, generated by quarkdocGenerate,
         // in the 'docs' directory.
         val dokkaOutputDir = layout.buildDirectory.file("docs")
@@ -140,6 +146,7 @@ distributions.main {
 
 tasks.installDist {
     dependsOn(quarkdocGenerate)
+    dependsOn(":quarkdown-html:bundleThirdParty")
 }
 
 tasks.distZip {

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/CliOptions.kt

@@ -9,6 +9,7 @@ import java.io.File
  * @param source main source file to process
  * @param outputDirectory the output directory to save resource in, if set
  * @param libraryDirectory the directory to load .qd library files from
+ * @param htmlLibraryDirectory the directory containing third-party HTML library files
  * @param rendererName name of the renderer to use to generate the output for
  * @param clean whether to clean the output directory before generating new files
  * @param pipe whether to output the rendered result to standard output, suitable for piping
@@ -21,6 +22,7 @@ data class CliOptions(
     val source: File?,
     val outputDirectory: File?,
     val libraryDirectory: File?,
+    val htmlLibraryDirectory: File?,
     val rendererName: String,
     val clean: Boolean,
     val pipe: Boolean,

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/exec/ExecuteCommand.kt

@@ -32,8 +32,8 @@ import java.io.File
 const val DEFAULT_OUTPUT_DIRECTORY = "output"
 
 /**
- * Name of the default directory to load libraries from.
- * The default value is relative to the executable JAR file location, and points to the `lib/qd` directory of the distribution archive.
+ * Default directory to load Quarkdown libraries from.
+ * The default value is relative to the executable JAR file location, and points to the `lib/qd` directory of the distribution layout.
  * It can be overridden by the user.
  */
 val DEFAULT_LIBRARY_DIRECTORY = ".." + File.separator + "lib" + File.separator + "qd"
@@ -202,6 +202,7 @@ abstract class ExecuteCommand(
             source = null,
             outputDirectory,
             libraryDirectory,
+            htmlLibraryDirectory = com.quarkdown.rendering.html.post.resources.ThirdPartyLibraryDirectory.path,
             renderer,
             clean,
             pipe = false,

quarkdown-cli/src/main/kotlin/com/quarkdown/cli/renderer/RendererRetriever.kt

@@ -32,8 +32,13 @@ class RendererRetriever(
     fun getRenderer(): (RendererFactory, Context) -> RenderingComponents =
         { factory, context ->
             when {
-                isHtmlPdf() -> factory.htmlPdf(context, createHtmlPdfExportOptions())
-                isHtml() -> factory.html(context)
+                isHtmlPdf() ->
+                    factory.htmlPdf(
+                        context,
+                        createHtmlPdfExportOptions(),
+                        libraryDirectory = options.htmlLibraryDirectory,
+                    )
+                isHtml() -> factory.html(context, libraryDirectory = options.htmlLibraryDirectory)
                 isPlainText() -> factory.plainText(context)
                 else -> throw IllegalArgumentException("Unsupported renderer: '${options.rendererName}'")
             }

quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/output/FileReferenceOutputResource.kt

@@ -0,0 +1,20 @@
+package com.quarkdown.core.pipeline.output
+
+import java.io.File
+
+/**
+ * An [OutputResource] backed by a file on the filesystem.
+ * Instead of holding content in memory, it references a [file] that is copied to the output location on save.
+ *
+ * This is efficient for bundling large pre-existing files (e.g. third-party libraries)
+ * where loading bytes into memory would be unnecessary overhead.
+ *
+ * @param name the output file name (with extension, since the original file name is used as-is)
+ * @param file the source file to copy
+ */
+data class FileReferenceOutputResource(
+    override val name: String,
+    val file: File,
+) : OutputResource {
+    override fun <T> accept(visitor: OutputResourceVisitor<T>): T = visitor.visit(this)
+}

quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/output/OutputResourceVisitor.kt

@@ -10,4 +10,6 @@ interface OutputResourceVisitor<T> {
     fun visit(artifact: BinaryOutputArtifact): T
 
     fun visit(group: OutputResourceGroup): T
+
+    fun visit(resource: FileReferenceOutputResource): T
 }

quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/output/visitor/CopyOutputResourceVisitor.kt

@@ -1,6 +1,7 @@
 package com.quarkdown.core.pipeline.output.visitor
 
 import com.quarkdown.core.pipeline.output.BinaryOutputArtifact
+import com.quarkdown.core.pipeline.output.FileReferenceOutputResource
 import com.quarkdown.core.pipeline.output.OutputResource
 import com.quarkdown.core.pipeline.output.OutputResourceGroup
 import com.quarkdown.core.pipeline.output.OutputResourceVisitor
@@ -17,6 +18,8 @@ class CopyOutputResourceVisitor(
 
     override fun visit(artifact: BinaryOutputArtifact): OutputResource = artifact.copy(name = name)
 
+    override fun visit(resource: FileReferenceOutputResource): OutputResource = resource.copy(name = name)
+
     override fun visit(group: OutputResourceGroup): OutputResource = group.copy(name = name)
 }
 

quarkdown-core/src/main/kotlin/com/quarkdown/core/pipeline/output/visitor/FileResourceExporter.kt

@@ -2,6 +2,7 @@ package com.quarkdown.core.pipeline.output.visitor
 
 import com.quarkdown.core.pipeline.output.ArtifactType
 import com.quarkdown.core.pipeline.output.BinaryOutputArtifact
+import com.quarkdown.core.pipeline.output.FileReferenceOutputResource
 import com.quarkdown.core.pipeline.output.OutputArtifact
 import com.quarkdown.core.pipeline.output.OutputResource
 import com.quarkdown.core.pipeline.output.OutputResourceGroup
@@ -79,6 +80,18 @@ class FileResourceExporter(
             }
         }
 
+    /**
+     * Copies a [FileReferenceOutputResource] to the output location.
+     * @return the copied file
+     */
+    override fun visit(resource: FileReferenceOutputResource) =
+        File(location, resource.name).also {
+            if (write) {
+                it.parentFile?.mkdirs()
+                resource.file.copyTo(it, overwrite = true)
+            }
+        }
+
     /**
      * Saves an [OutputResourceGroup] to a directory which contains its nested files.
      * @return the directory file itself

quarkdown-html/build.gradle.kts

@@ -1,7 +1,6 @@
 
 import com.github.gradle.node.npm.task.NpmTask
 import com.github.gradle.node.npm.task.NpxTask
-import groovy.json.JsonOutput
 
 plugins {
     kotlin("jvm")
@@ -25,28 +24,30 @@ dependencies {
 /*
 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).
+Libraries from node_modules are copied into build/thirdparty/
+at Gradle build time, so they are included in the distribution archive
+and loaded from the filesystem at runtime.
 
 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 thirdPartyDir =
+    layout.buildDirectory
+        .dir("thirdparty")
+        .get()
+        .asFile
 val nodeModules = projectDir.resolve("node_modules")
 val scssThirdParty = projectDir.resolve("src/main/scss/thirdparty")
+val staticFontsDir = projectDir.resolve("src/main/fonts")
 
 /**
- * Declarative specification for copying a library from `node_modules` into `lib/`.
+ * Declarative specification for copying a library from `node_modules` into `build/thirdparty/`.
  * Multiple specs may share the same [target] (their files are merged into one directory).
  *
- * @param target output directory name under `lib/`
+ * @param target output directory name under `build/thirdparty/`
  * @param source path relative to `node_modules/`
  * @param includes glob patterns to select files (empty = everything)
  */
@@ -57,7 +58,7 @@ data class LibrarySpec(
 )
 
 /**
- * All libraries to copy from `node_modules` into JAR resources.
+ * All libraries to copy from `node_modules` into the distribution.
  * To add a new library, append a `LibrarySpec` entry here.
  */
 val librariesToBundle =
@@ -72,7 +73,7 @@ val librariesToBundle =
     )
 
 /**
- * @fontsource packages to bundle. Each is placed in its own `lib/fonts/{name}/` directory
+ * @fontsource packages to bundle. Each is placed in its own `build/thirdparty/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(...)`.
  */
@@ -109,19 +110,19 @@ val bundleHighlightJs =
                 "--format=iife",
                 "--global-name=hljs",
                 "--minify",
-                "--outfile=${libDir.resolve("highlight.js/highlight.min.js")}",
+                "--outfile=${thirdPartyDir.resolve("highlight.js/highlight.min.js")}",
             ),
         )
     }
 
 /**
  * Main bundling task: copies libraries, bundles fontsource fonts,
- * copies hljs SCSS partials, and generates the nested manifest JSON.
+ * and copies hljs SCSS partials.
  */
 val bundleThirdParty =
     tasks.register<DefaultTask>("bundleThirdParty") {
         group = "build"
-        description = "Bundles third-party libraries from node_modules into JAR resources"
+        description = "Bundles third-party libraries from node_modules into the distribution"
         dependsOn(tasks.npmInstall)
         dependsOn(bundleHighlightJs)
 
@@ -131,28 +132,32 @@ val bundleThirdParty =
                     from(nodeModules.resolve(source)) {
                         if (includes.isNotEmpty()) include(includes)
                     }
-                    into(libDir.resolve(target))
+                    into(thirdPartyDir.resolve(target))
                 }
             }
 
             fontsourcePackages.forEach { fontName ->
                 bundleFontsource("fonts/$fontName", listOf(fontName))
             }
 
+            // Copy static (non-npm) font files from the source tree.
+            copy {
+                from(staticFontsDir)
+                into(thirdPartyDir.resolve("fonts"))
+            }
+
             scssThirdParty.mkdirs()
             hljsScssPartials.forEach { (source, partialName) ->
                 nodeModules
                     .resolve("highlight.js/styles/$source")
                     .copyTo(scssThirdParty.resolve("_$partialName.scss"), overwrite = true)
             }
-
-            generateNestedManifest()
         }
     }
 
 /**
  * Auto-discovers latin-subset woff2 files from the given @fontsource packages,
- * copies them into the given [targetSubdir] under `lib/`, and generates a `fonts.css`
+ * copies them into the given [targetSubdir] under `build/thirdparty/`, and generates a `fonts.css`
  * with `@font-face` declarations derived from the file naming convention.
  *
  * @fontsource files follow the pattern `{font}-latin-{weight}-{style}.woff2`,
@@ -162,7 +167,7 @@ fun bundleFontsource(
     targetSubdir: String,
     fontNames: List<String>,
 ) {
-    val targetDir = libDir.resolve(targetSubdir)
+    val targetDir = thirdPartyDir.resolve(targetSubdir)
     val cssBuilder = StringBuilder()
 
     // Matches e.g. "lato-latin-400-normal.woff2" -> (lato, 400, normal)
@@ -201,45 +206,6 @@ fun bundleFontsource(
     targetDir.resolve("fonts.css").writeText(cssBuilder.toString())
 }
 
-/**
- * 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"] }
- *   }
- * }
- * ```
- */
-fun generateNestedManifest() {
-    fun dirToJson(dir: File): Map<String, Any> =
-        buildMap {
-            dir
-                .listFiles()
-                ?.filter { it.isFile && it.name != "third-party-manifest.json" }
-                ?.map { it.name }
-                ?.sorted()
-                ?.takeIf { it.isNotEmpty() }
-                ?.let { put("_files", it) }
-
-            dir
-                .listFiles()
-                ?.filter { it.isDirectory }
-                ?.sortedBy { it.name }
-                ?.forEach { put(it.name, dirToJson(it)) }
-        }
-
-    libDir
-        .resolve("third-party-manifest.json")
-        .writeText(JsonOutput.prettyPrint(JsonOutput.toJson(dirToJson(libDir))))
-}
-
 // SCSS and TypeScript bundling
 
 val scssDir = projectDir.resolve("src/main/scss")
@@ -287,7 +253,16 @@ val bundleTypeScript =
 tasks.processResources {
     dependsOn(tasks.compileSass)
     dependsOn(bundleTypeScript)
-    dependsOn(bundleThirdParty)
+    // bundleThirdParty no longer needed for processResources since libraries are not in the JAR.
+    // It is still needed for compileSass (hljs SCSS partials).
+
+    // Write the absolute path of the third-party directory into a resource file
+    // so the CLI can locate it at runtime regardless of how it was launched.
+    doLast {
+        val propsDir = destinationDir.resolve("render")
+        propsDir.mkdirs()
+        propsDir.resolve("thirdparty.path").writeText(thirdPartyDir.absolutePath)
+    }
 }
 
 // Tests