link directives - properly support custom link text as documented

core/shared/src/main/scala/laika/directive/DirectiveSupport.scala

@@ -21,6 +21,7 @@ import laika.ast.{
   DocumentCursor,
   InvalidSpan,
   LinkIdReference,
+  LinkPathReference,
   NoOpt,
   Options,
   Replace,
@@ -120,14 +121,38 @@ class DirectiveSupport(
     def unresolvedMessage: String = s"unresolved api directive for type $typeName"
   }
 
+  private case class LinkDirectiveResolver2(
+      ref: LinkPathReference,
+      directiveName: String,
+      typeName: String,
+      source: SourceFragment,
+      options: Options = NoOpt
+  ) extends SpanResolver {
+    type Self = LinkDirectiveResolver2
+
+    def resolve(cursor: DocumentCursor): Span = linkDirectiveMap.get(directiveName)
+      .fold[Span](InvalidSpan(s"Unknown link directive: $directiveName", source)) { dir =>
+        dir(typeName, cursor).fold(
+          err => InvalidSpan(s"Invalid link directive: $err", source),
+          res => res.copy(content = ref.content, options = res.options + ref.options)
+        )
+      }
+
+    def withOptions(options: Options): LinkDirectiveResolver2 = copy(options = options)
+
+    def runsIn(phase: RewritePhase): Boolean = phase.isInstanceOf[RewritePhase.Render]
+
+    def unresolvedMessage: String = s"unresolved api directive for type $typeName"
+  }
+
   override lazy val rewriteRules: RewritePhaseBuilder = { case RewritePhase.Resolve =>
     if (strictMode) Nil
     else
       Seq(RewriteRules.forSpans {
-        case ref: LinkIdReference if ref.ref.startsWith("@:") =>
-          linkParser.parse(ref.ref.drop(2)).toEither.fold(
+        case ref: LinkPathReference if ref.path.toString.startsWith("@:") =>
+          linkParser.parse(ref.path.toString.drop(2)).toEither.fold(
             err => Replace(InvalidSpan(s"Invalid link directive: $err", ref.source)),
-            res => Replace(LinkDirectiveResolver(ref, res._1, res._2, ref.source, ref.options))
+            res => Replace(LinkDirectiveResolver2(ref, res._1, res._2, ref.source, ref.options))
           )
       }.asBuilder)
   }

core/shared/src/test/scala/laika/directive/SpanDirectiveAPISpec.scala

@@ -528,7 +528,7 @@ class SpanDirectiveAPISpec extends FunSuite with TestSourceBuilders with RenderP
 
   test("link directive inside a native link expression") {
     new LinkParser with LinkDirectiveSetup {
-      val input = "aa [RFC-222][@:rfc(222)] bb"
+      val input = "aa [RFC-222](@:rfc(222)) bb"
       assertEquals(
         parseAsMarkdown(input),
         Right(
@@ -544,13 +544,13 @@ class SpanDirectiveAPISpec extends FunSuite with TestSourceBuilders with RenderP
 
   test("unknown link directive") {
     new LinkParser with LinkDirectiveSetup {
-      val input = "aa [RFC-222][@:rfx(222)] bb"
+      val input = "aa [RFC-222](@:rfx(222)) bb"
       assertEquals(
         parseAsMarkdown(input),
         Right(
           Paragraph(
             Text("aa "),
-            invalid("[RFC-222][@:rfx(222)]", "Unknown link directive: rfx", defaultPath),
+            invalid("[RFC-222](@:rfx(222))", "Unknown link directive: rfx", defaultPath),
             Text(" bb")
           )
         )
@@ -560,14 +560,14 @@ class SpanDirectiveAPISpec extends FunSuite with TestSourceBuilders with RenderP
 
   test("invalid link directive") {
     new LinkParser with LinkDirectiveSetup {
-      val input = "aa [RFC-222][@:rfc(foo)] bb"
+      val input = "aa [RFC-222](@:rfc(foo)) bb"
       assertEquals(
         parseAsMarkdown(input),
         Right(
           Paragraph(
             Text("aa "),
             invalid(
-              "[RFC-222][@:rfc(foo)]",
+              "[RFC-222](@:rfc(foo))",
               "Invalid link directive: Not a valid RFC id: foo",
               defaultPath
             ),
@@ -580,15 +580,15 @@ class SpanDirectiveAPISpec extends FunSuite with TestSourceBuilders with RenderP
 
   test("invalid link directive syntax") {
     new LinkParser with LinkDirectiveSetup {
-      val input = "aa [RFC-222][@:rfc foo] bb"
+      val input = "aa [RFC-222](@:rfc!foo) bb"
       assertEquals(
         parseAsMarkdown(input),
         Right(
           Paragraph(
             Text("aa "),
             invalid(
-              "[RFC-222][@:rfc foo]",
-              "Invalid link directive: `(' expected but `f` found",
+              "[RFC-222](@:rfc!foo)",
+              "Invalid link directive: `(' expected but `!` found",
               defaultPath
             ),
             Text(" bb")

core/shared/src/test/scala/laika/directive/std/LinkDirectiveSpec.scala

@@ -47,6 +47,19 @@ class LinkDirectiveSpec extends FunSuite with ParagraphCompanionShortcuts with T
         Right(RootElement(p(Text("aa "), expected, Text(" bb"))))
       )
 
+    def runCustom(
+        directiveInput: String,
+        expected: Span,
+        withoutConfig: Boolean = false
+    ): Unit = {
+      val input =
+        if (withoutConfig) lineInput(directiveInput) else configInput(lineInput(directiveInput))
+      assertEquals(
+        parse(input).map(_.content),
+        Right(RootElement(p(Text("aa "), expected, Text(" bb"))))
+      )
+    }
+
     def runTypeBlock(block: String, expected: Span*): Unit = {
       val input = s"""aa
                      |
@@ -88,6 +101,14 @@ class LinkDirectiveSpec extends FunSuite with ParagraphCompanionShortcuts with T
     )
   }
 
+  test("api directive - with custom link text in native Markdown link syntax") {
+    Api.runCustom(
+      "[Custom link text](@:api(def.bar.Baz))",
+      SpanLink.external("https://default.api/def/bar/Baz.html")("Custom link text")
+        .withStyles("api")
+    )
+  }
+
   test("api directive - strip the $ postfix from the link text") {
     Api.runType(
       "def.bar.Baz$",
@@ -200,6 +221,19 @@ class LinkDirectiveSpec extends FunSuite with ParagraphCompanionShortcuts with T
         Right(RootElement(p(Text("aa "), expected, Text(" bb"))))
       )
 
+    def runCustom(
+        directiveInput: String,
+        expected: Span,
+        withoutConfig: Boolean = false
+    ): Unit = {
+      val input =
+        if (withoutConfig) lineInput(directiveInput) else configInput(lineInput(directiveInput))
+      assertEquals(
+        parse(input).map(_.content),
+        Right(RootElement(p(Text("aa "), expected, Text(" bb"))))
+      )
+    }
+
   }
 
   test("source directive - span link based on the default base URI") {
@@ -209,6 +243,14 @@ class LinkDirectiveSpec extends FunSuite with ParagraphCompanionShortcuts with T
     )
   }
 
+  test("source directive - with custom link text in native Markdown link syntax") {
+    Source.runCustom(
+      "[Custom link text](@:source(def.bar.Baz))",
+      SpanLink.external("https://default.source/def/bar/Baz.scala")("Custom link text")
+        .withStyles("source")
+    )
+  }
+
   test("source directive - span link based on the longest prefix match") {
     Source.runType(
       "foo.bar.Baz",

project/plugins.sbt

@@ -10,4 +10,4 @@ addSbtPlugin("org.scala-js" % "sbt-scalajs" % "1.13.2")
 
 addSbtPlugin("org.portable-scala" % "sbt-scalajs-crossproject" % "1.3.2")
 
-addSbtPlugin("org.planet42" % "laika-sbt" % "0.19.2")
+addSbtPlugin("org.planet42" % "laika-sbt" % "0.19.3")