prepare 0.19.4 release

build.sbt

@@ -111,7 +111,7 @@ lazy val docs = project.in(file("docs"))
     Laika / target            := baseDirectory.value / "target",
     mdocIn                    := baseDirectory.value / "src",
     mdocVariables             := Map(
-      "LAIKA_VERSION" -> "0.19.3"
+      "LAIKA_VERSION" -> "0.19.4"
     ),
     mdocExtraArguments        := Seq("--no-link-hygiene")
   )

core/shared/src/main/scala/laika/bundle/ExtensionBundle.scala

@@ -280,7 +280,7 @@ object ExtensionBundle {
     override val slugBuilder: Option[String => String] = Some(SlugBuilder.default)
 
     override val baseConfig: Config =
-      ConfigBuilder.empty.withValue("laika.version", "0.19.3").build
+      ConfigBuilder.empty.withValue("laika.version", "0.19.4").build
 
     override val parsers: ParserBundle = ParserBundle(
       styleSheetParser = Some(CSSParsers.styleDeclarationSet)

core/shared/src/main/scala/laika/rewrite/link/LinkValidator.scala

@@ -67,10 +67,11 @@ private[laika] class LinkValidator(
   private val excludedPaths = {
     val excludedExplicitly = {
       // backwards-compatibility mode for 0.19.x
-      val newKey    = "laika.links.validation.excluded"
-      val oldKey    = "laika.links.excludeFromValidation"
-      val actualKey = if (cursor.config.hasKey(newKey)) newKey else oldKey
-      cursor.config.get[Seq[Path]](actualKey).getOrElse(Nil)
+      val newKey   = "laika.links.validation.excluded"
+      val oldKey   = "laika.links.excludeFromValidation"
+      val newValue = cursor.config.get[Seq[Path]](newKey).getOrElse(Nil)
+      val oldValue = cursor.config.get[Seq[Path]](oldKey).getOrElse(Nil)
+      newValue ++ oldValue
     }
     excludedExplicitly ++ versionRoots
   }

core/shared/src/test/scala/laika/rewrite/LinkValidatorSpec.scala

@@ -19,7 +19,13 @@ package laika.rewrite
 import laika.ast.Path.Root
 import laika.ast.sample.{ BuilderKey, SampleTrees }
 import laika.ast._
-import laika.rewrite.link.{ InvalidTarget, LinkValidation, RecoveredTarget, ValidTarget }
+import laika.rewrite.link.{
+  InvalidTarget,
+  LinkConfig,
+  LinkValidation,
+  RecoveredTarget,
+  ValidTarget
+}
 import laika.rewrite.nav.TargetFormats
 import munit.FunSuite
 
@@ -29,6 +35,29 @@ class LinkValidatorSpec extends FunSuite {
 
   private val defaultLinkValidation = LinkValidation.Local
 
+  private def legacyTestCursor(linkConfig: LinkConfig): DocumentCursor = {
+    import laika.ast.sample.SampleConfig._
+
+    def doc2(key: BuilderKey): Seq[Block] = Seq(
+      Header(1, "Title").withOptions(Id("ref")),
+      Paragraph("text")
+    )
+
+    SampleTrees.sixDocuments
+      .root.config(siteBaseURL("https://external/"))
+      .doc4.config(targetFormats("html"))
+      .static2.config(targetFormats("html"))
+      .doc6.config(_.withValue(linkConfig).withValue(LinkValidation.Global()))
+      .staticDoc(Root / "static-1" / "doc-7.txt")
+      .staticDoc(Root / "static-2" / "doc-8.txt", "html")
+      .docContent(doc2 _)
+      .suffix("md")
+      .buildCursor // TODO - buildCursor should be available on doc6
+      .toOption
+      .flatMap(_.allDocuments.find(_.path == Root / "tree-2" / "doc-6.md"))
+      .get
+  }
+
   private def testCursor(docConfig: LinkValidation = defaultLinkValidation): DocumentCursor = {
     import laika.ast.sample.SampleConfig._
 
@@ -85,6 +114,14 @@ class LinkValidatorSpec extends FunSuite {
     )
   }
 
+  test("ignore invalid link target when target directory is excluded via deprecated property") {
+    val config = LinkConfig(excludeFromValidation = Seq(Root / "tree-1"))
+    assertEquals(
+      legacyTestCursor(config).validate(testTarget("../tree-1/doc-9.md")),
+      ValidTarget
+    )
+  }
+
   test("ignore invalid link target when validation is configured to be local") {
     assertEquals(
       testCursor().validate(testTarget("../tree-1/doc-9.md")),

docs/src/02-running-laika/03-configuration.md

@@ -176,7 +176,7 @@ When you need to work with different encodings you can override the default:
 ```scala mdoc:compile-only
 import scala.io.Codec
 
-laikaConfig := LaikaConfig.defaults.encoding(Codec.ISO8859)
+laikaConfig := LaikaConfig.defaults.withEncoding(Codec.ISO8859)
 ```
 
 @:choice(library)

docs/src/03-preparing-content/02-navigation.md

@@ -133,10 +133,10 @@ import laika.ast.ExternalTarget
 import laika.rewrite.link.{ LinkConfig, TargetDefinition }
 
 laikaConfig := LaikaConfig.defaults
-  .withConfigValue(LinkConfig(targets = Seq(
+  .withConfigValue(LinkConfig.empty.addTargets(
     TargetDefinition("Example 1", ExternalTarget("https://example1.com/")),
     TargetDefinition("Example 2", ExternalTarget("https://example2.com/"))
-  )))
+  ))
 ```
 
 @:choice(library)
@@ -151,10 +151,10 @@ val transformer = Transformer
   .from(Markdown)
   .to(HTML)
   .using(GitHubFlavor)
-  .withConfigValue(LinkConfig(targets = Seq(
+  .withConfigValue(LinkConfig.empty.addTargets(
     TargetDefinition("Example 1", ExternalTarget("https://example1.com/")),
     TargetDefinition("Example 2", ExternalTarget("https://example2.com/"))
-  )))
+  ))
   .build
 ```
 @:@
@@ -253,9 +253,9 @@ This directive requires the base URI to be defined in the project's configuratio
 import laika.rewrite.link.{ LinkConfig, ApiLinks }
 
 laikaConfig := LaikaConfig.defaults
-  .withConfigValue(LinkConfig(apiLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addApiLinks(
     ApiLinks(baseUri = "https://example.com/api")
-  )))
+  ))
 ```
 
 @:choice(library)
@@ -269,9 +269,9 @@ val transformer = Transformer
   .from(Markdown)
   .to(HTML)
   .using(GitHubFlavor)
-  .withConfigValue(LinkConfig(apiLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addApiLinks(
     ApiLinks(baseUri = "https://example.com/api")
-  )))
+  ))
   .build
 ```
 @:@
@@ -286,10 +286,10 @@ while keeping one base URI as a default for all packages that do not match any p
 import laika.rewrite.link.{ LinkConfig, ApiLinks }
 
 laikaConfig := LaikaConfig.defaults
-  .withConfigValue(LinkConfig(apiLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addApiLinks(
     ApiLinks(baseUri = "https://example.com/api"),
     ApiLinks(baseUri = "https://somewhere-else/", packagePrefix = "com.lib42")
-  )))
+  ))
 ```
 
 @:choice(library)
@@ -303,10 +303,10 @@ val transformer = Transformer
   .from(Markdown)
   .to(HTML)
   .using(GitHubFlavor)
-  .withConfigValue(LinkConfig(apiLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addApiLinks(
     ApiLinks(baseUri = "https://example.com/api"),
     ApiLinks(baseUri = "https://somewhere-else/", packagePrefix = "com.lib42")
-  )))
+  ))
   .build
 ```
 
@@ -334,9 +334,9 @@ This directive requires the base URI and suffix to be defined in the project's c
 import laika.rewrite.link.{ LinkConfig, SourceLinks }
 
 laikaConfig := LaikaConfig.defaults
-  .withConfigValue(LinkConfig(sourceLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addSourceLinks(
     SourceLinks(baseUri = "https://github.com/team/project", suffix = "scala")
-  )))
+  ))
 ```
 
 @:choice(library)
@@ -350,9 +350,9 @@ val transformer = Transformer
   .from(Markdown)
   .to(HTML)
   .using(GitHubFlavor)
-  .withConfigValue(LinkConfig(sourceLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addSourceLinks(
      SourceLinks(baseUri = "https://github.com/team/project", suffix = "scala")
-  )))
+  ))
   .build
 ```
 @:@
@@ -367,7 +367,7 @@ while keeping one base URI as a default for all packages that do not match any p
 import laika.rewrite.link.{ LinkConfig, SourceLinks }
 
 laikaConfig := LaikaConfig.defaults
-  .withConfigValue(LinkConfig(sourceLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addSourceLinks(
     SourceLinks(
       baseUri = "https://github.com/team/project", 
       suffix = "scala"
@@ -377,7 +377,7 @@ laikaConfig := LaikaConfig.defaults
       suffix = "scala", 
       packagePrefix = "com.lib42"
     )
-  )))
+  ))
 ```
 
 @:choice(library)
@@ -391,7 +391,7 @@ val transformer = Transformer
   .from(Markdown)
   .to(HTML)
   .using(GitHubFlavor)
-  .withConfigValue(LinkConfig(sourceLinks = Seq(
+  .withConfigValue(LinkConfig.empty.addSourceLinks(
     SourceLinks(
       baseUri = "https://github.com/team/project", 
       suffix = "scala"
@@ -401,7 +401,7 @@ val transformer = Transformer
       suffix = "scala", 
       packagePrefix = "com.lib42"
     )
-  )))
+  ))
   .build
 ```
 

docs/src/03-preparing-content/03-theme-settings.md

@@ -1006,6 +1006,37 @@ Helium.defaults
 ```
 
 
+Mermaid Diagrams
+----------------
+
+Helium supports Mermaid diagrams enclosed in fenced code blocks.
+In contrast to most other functionality in the theme, it is only available for HTML output,
+not for EPUB or PDF.
+
+A small sample diagram like this:
+
+````markdown
+```mermaid
+graph TD 
+A[Client] --> B[Load Balancer] 
+B --> C[Server-1] 
+B --> D[Server-2]
+```
+````
+
+will render in this theme like below:
+
+```mermaid
+graph TD 
+A[Client] --> B[Load Balancer] 
+B --> C[Server-1] 
+B --> D[Server-2]
+```
+
+It will pick up the theme colors you have defined for Helium, and cannot be configured separately.
+See [Theme Colors] above for how to configure the Helium color sets.
+
+
 Custom Templates
 ----------------
 

docs/src/07-reference/06-release-notes.md

@@ -2,6 +2,61 @@
 Release Notes
 =============
 
+0.19.4 (Sep 10, 2023)
+---------------------
+
+* **New support for mermaid diagrams in the Helium theme.**
+
+  Mermaid diagrams can now be included in standard fenced code blocks when using the default Helium theme.
+  The diagram colors will automatically adjust to the theme color configured for Helium.
+  This functionality is only available for HTML output, not EPUB or PDF.
+
+* **AST rendering in the preview server**
+
+  The preview server now support the rendering of the document AST for any page by adding the `/ast` path postfix.
+  This enables users to inspect the model in cases they want to write render overrides or rewrite rules and
+  are not sure what node types to match on.
+
+* **Better defaults & new API for configuring link validation**
+
+  The defaults for link validation remain the same for plugin users, but are improved for API users
+  where validation was on by default even when parsing a single input string that has no access to the
+  surrounding directory, meaning that all validation was futile.
+  It also comes with new configuration types to overwrite the defaults.
+
+* **New options for including CSS & JavaScript resources**
+
+  Previous support was limited in only supported local resources.
+  The new APIs support linking external or inline resources, setting common attributes like `defer`
+  and add support for conditional inclusion where the document AST or configuration can be inspected before
+  deciding on whether a resource should be included.
+
+* **Better & safer AST builders**
+
+  Introduces `DocumentTree.builder` as a safer and more convenient way to construct an AST model.
+  The old `apply` entry point of the case class is deprecated. It was too low-level and error-prone
+  due to the way several aspects of the model inherit properties from parent which might be missed
+  with manual construction.
+
+* **Spec compliance**
+
+  * Bullet lists in Markdown do no longer require a preceding blank line to be detected.
+    (enumerated lists remain unchanged to match the spec).
+  * Support nested parenthesis in URLs
+
+* Bug fixes
+    * Fix CSS for code spans in navigation items which were invisible in some cases.
+    * Properly support custom link text for link directives.
+    * Introduce substitution variable `cursor.currentDocument.rawTitle` that prevents
+      the rendering of markup where not supported (e.g. in the `<title>` element).
+
+* Deprecations
+    * introduces a small set of deprecations that will help with migrating to 1.0
+
+* Dependencies
+    * cats-core 2.10.0, cats-effect 3.5.1, fs2 3.9.1, http4s 0.23.23
+
+
 0.19.3 (July 5, 2023)
 ---------------------
 

project/ManualSettings.scala

@@ -179,7 +179,7 @@ object ManualSettings {
         )
       ),
       subtitle = Some(text.mainDesc),
-      latestReleases = Seq(ReleaseInfo("Latest Release", "0.19.3")),
+      latestReleases = Seq(ReleaseInfo("Latest Release", "0.19.4")),
       license = Some("Apache 2.0"),
       documentationLinks = Seq(
         TextLink.internal(Root / "01-about-laika" / "01-features.md", "Features"),