Ignore shebang headers in scala code blocks in Markdown inputs

modules/build/src/main/scala/scala/build/internal/markdown/MarkdownOpenFence.scala

@@ -2,6 +2,7 @@ package scala.build.internal.markdown
 
 import scala.build.Position
 import scala.build.errors.MarkdownUnclosedBackticksError
+import scala.build.preprocessing.SheBang
 
 /** Representation for an open code block in Markdown. (open meaning the closing backticks haven't
   * yet been parsed or they aren't at all present)
@@ -37,9 +38,11 @@ case class MarkdownOpenFence(
   ): MarkdownCodeBlock = {
     val start: Int               = tickStartLine + 1
     val bodyLines: Array[String] = lines.slice(start, tickEndLine)
+    val body                     = bodyLines.mkString("\n")
+    val (bodyWithNoSheBang, _)   = SheBang.ignoreSheBangLines(body)
     MarkdownCodeBlock(
       info.split("\\s+").toList, // strip info by whitespaces
-      bodyLines.mkString("\n"),
+      bodyWithNoSheBang,
       start,          // snippet has to begin in the new line
       tickEndLine - 1 // ending backticks have to be placed below the snippet
     )

modules/build/src/test/scala/scala/build/tests/markdown/MarkdownCodeBlockTests.scala

@@ -46,6 +46,28 @@ class MarkdownCodeBlockTests extends munit.FunSuite {
     expect(actualResult == expectedResult)
   }
 
+  test("shebang line is ignored in plain scala code blocks") {
+    val code = """println("Hello")""".stripMargin
+    val markdown =
+      s"""# Some snippet
+         |
+         |```scala
+         |#!/usr/bin/env -S scala-cli shebang
+         |$code
+         |```
+         |""".stripMargin
+    val expectedResult =
+      MarkdownCodeBlock(
+        info = PlainScalaInfo,
+        body = "\n" + code,
+        startLine = 3,
+        endLine = 4
+      )
+    val Right(Seq(actualResult: MarkdownCodeBlock)) =
+      MarkdownCodeBlock.findCodeBlocks(os.sub / "Example.md", markdown)
+    expect(actualResult == expectedResult)
+  }
+
   test("a raw Scala code block is extracted correctly from markdown") {
     val code = """object Main extends App {
                  |  println("Hello")
@@ -69,6 +91,31 @@ class MarkdownCodeBlockTests extends munit.FunSuite {
     expect(actualResult == expectedResult)
   }
 
+  test("shebang line is ignored in raw scala code blocks") {
+    val code =
+      """object Main extends App {
+        |  println("Hello")
+        |}""".stripMargin
+    val markdown =
+      s"""# Some snippet
+         |
+         |```scala raw
+         |#!/usr/bin/env -S scala-cli shebang
+         |$code
+         |```
+         |""".stripMargin
+    val expectedResult =
+      MarkdownCodeBlock(
+        info = RawScalaInfo,
+        body = "\n" + code,
+        startLine = 3,
+        endLine = 6
+      )
+    val Right(Seq(actualResult: MarkdownCodeBlock)) =
+      MarkdownCodeBlock.findCodeBlocks(os.sub / "Example.md", markdown)
+    expect(actualResult == expectedResult)
+  }
+
   test("a test Scala snippet is extracted correctly from markdown") {
     val code =
       """//> using lib "org.scalameta::munit:0.7.29"

website/docs/guides/markdown.md

@@ -337,6 +337,18 @@ world
 
 </ChainedSnippets>
 
+## `shebang` header and Markdown code blocks
+The `shebang` line in `scala` code blocks inside a markdown input are always ignored.
+You can use them (i.e. to give an example of their usage), but they do not change how the code is handled.
+
+````markdown
+## Self executable Scala script
+```scala
+#!/usr/bin/env -S scala-cli shebang
+println("Hello world")
+```
+````
+
 ## `using` directives and Markdown code blocks
 
 It is possible to define `using` directives at the beginning of a `scala` code block inside a markdown input.