Document recent features & changes affecting working markdown inputs

- `.md` sources in zipped archives
- `.md` sources in GitHub gists
- remote `.md` sources
- piping Markdown code
- Markdown snippets

Author: Gedochao

website/docs/commands/basics.md

@@ -22,7 +22,7 @@ in which case it defaults to one of the sub-commands based on context:
 - if any inputs were passed, it defaults to the `run` sub-command
     - and so, `scala-cli a.scala` runs your `a.scala` file
 - additionally, when no inputs were passed, it defaults to the `run` sub-command in the following scenarios:
-    - if a snippet was passed with `--execute-script`, `--execute-scala` or `--execute-java`
+    - if a snippet was passed with `-e`, `--execute-script`, `--execute-scala`, `--execute-java` or `--execute-markdown`
     - if a main class was passed with the `--main-class` option alongside an extra `--classpath`
 - otherwise if no inputs were passed, it defaults to the `repl` sub-command
 
@@ -207,6 +207,14 @@ You can also pipe code to `scala-cli` for execution:
   echo 'class Hello { public static void main(String args[]) { System.out.println("Hello"); } }' | scala-cli _.java
   # Hello
   ```
+- Markdown code (experimental)
+  ```bash
+  echo '# Example Snippet
+  ```scala
+  println("Hello")
+  ```' | scala-cli _.md
+  # Hello
+  ```
 
 More details in the [Piping guide](../guides/piping.md).
 

website/docs/cookbooks/gists.md

@@ -3,6 +3,8 @@ title: Sharing and testing code with GitHub gists
 sidebar_position: 6
 ---
 
+import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+
 ## Running code from gists
 
 `scala-cli` lets you run Scala code straight from GitHub gists, without the need to manually download them first.
@@ -78,4 +80,30 @@ scala-cli https://gist.github.com/lwronski/7ee12fa4b8b8bac3211841273df82080
 1,2,3,4
 -->
 
-it will print `1,2,3,4` to the standard output.
+it will print `1,2,3,4` to the standard output.
+
+## Gists and Markdown code
+
+:::note
+This feature is a work in progress and should currently be treated as experimental.
+Markdown sources are ignored by default unless passed explicitly as inputs.
+You can enable including non-explicit `.md` inputs by passing the `--enable-markdown` option.
+:::
+
+It is possible to run markdown sources from a GitHub gist. 
+The gist is technically treated as a zipped archive (which it is downloaded as), so it is necessary to pass
+the `--enable-markdown` option alongside the gist URL to run any contained Markdown sources.
+
+<ChainedSnippets>
+
+```bash
+scala-cli https://gist.github.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839 --enable-markdown
+```
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
+You can find more information on working with Markdown in the [Markdown guide](../guides/markdown.md).

website/docs/guides/markdown.md

@@ -13,7 +13,123 @@ Markdown sources are ignored by default unless passed explicitly as inputs.
 You can enable including non-explicit `.md` inputs by passing the `--enable-markdown` option.
 :::
 
-## Plain `scala` snippets
+## Markdown inputs
+
+### On-disk markdown sources
+
+You can pass local `.md` inputs by passing their path to Scala CLI (as you would for any other kind of input).
+
+```bash ignore
+scala-cli hello.md
+```
+
+`.md` sources inside of directories are ignored by default, unless the `--enable-markdown` option is passed.
+
+```bash ignore
+scala-cli dir-with-markdown --enable-markdown
+```
+
+### Zipped archives
+
+Scala CLI can run `.md` sources inside a `.zip` archive.
+Same as with directories,  `.md` sources inside zipped archives are ignored by default, unless
+the `--enable-markdown` option is passed.
+
+```bash ignore
+scala-cli archive-with-markdown.zip --enable-markdown
+```
+
+### Remote inputs
+
+:::warning
+Running unverified code from the Internet can be very handy for *trusted* sources, but it can also be really dangerous,
+since Scala CLI does not provide any sandboxing at this moment.
+
+Make sure that you trust the code that you are about to run.
+:::
+
+#### URLs
+
+You can also pass a URL pointing to a `.md` file to run it with Scala CLI.
+
+<ChainedSnippets>
+
+```bash
+scala-cli https://gist.githubusercontent.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839/raw/4c5ce7593e19f1390555221e0d076f4b02f4b4fd/example.md
+```
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
+#### Github Gist
+
+Scala CLI accepts GitHub Gist URLs.
+The gist is technically treated as a zipped archive (which it is downloaded as), so it is necessary to pass
+the `--enable-markdown` option alongside the gist URL to run any contained Markdown sources.
+
+<ChainedSnippets>
+
+```bash
+scala-cli https://gist.github.com/Gedochao/6415211eeb8ca4d8d6db123f83f0f839 --enable-markdown
+```
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
+You can find more information on running GitHub Gists in the [gists cookbook](../cookbooks/gists.md).
+
+### Piped Markdown code
+
+Instead of passing paths to your Markdown sources, you can also pipe your code via standard input:
+
+<ChainedSnippets>
+
+```bash
+echo '# Example Snippet
+```scala
+println("Hello")
+```' | scala-cli _.md
+```
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
+You can find more information on piped sources in the [piping guide](./piping.md).
+
+### Markdown code as a command line snippet
+
+It is also possible to pass Markdown code as a snippet directly from the command line.
+
+<ChainedSnippets>
+
+````bash
+scala-cli run --markdown-snippet '# Markdown snippet
+with a code block
+```scala
+println("Hello")
+```'
+````
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
+You can find more information on command line snippets in the [snippets guide](./snippets.md).
+
+## Markdown code blocks
+
+### Plain `scala` snippets
 
 ````markdown title=Example.md
 # Example
@@ -85,7 +201,7 @@ Example1_md Example2_md
 
 </ChainedSnippets>
 
-## `scala raw` snippets
+### `scala raw` snippets
 
 You can mark a `scala` code block with the `raw` keyword, indicating that this snippet should not be wrapped as a script
 and should instead be treated as is. This is the equivalent of code in a `.scala` file. For a `raw` snippet to be
@@ -116,7 +232,7 @@ Hello from Markdown
 
 </ChainedSnippets>
 
-## `scala test` snippets
+### `scala test` snippets
 
 It is possible to run tests from `scala` code blocks marked as `test`. This is similar to `raw` snippets in that the
 code is not wrapped and is treated as is.
@@ -150,7 +266,7 @@ Test:
 
 </ChainedSnippets>
 
-## `reset` scope for `scala` snippets
+### `reset` scope for `scala` snippets
 
 When multiple plain `scala` snippets are used in a single `.md` file, by default they are actually treated as a single
 script. They share context and when run, are executed one after another, as if they were all in a single `.sc` file.
@@ -199,11 +315,94 @@ world
 
 </ChainedSnippets>
 
+## `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.
+This is supported for all `scala` code block flavours.
+
+````markdown title=UsingDirectives.md
+# Using directives in `.md` inputs
+
+## `scala raw` example
+```scala raw
+//> using lib "com.lihaoyi::pprint:0.8.0"
+object Printer {
+  def printHello(): Unit = pprint.pprintln("Hello")
+}
+```
+
+## Plain `scala` example
+```scala
+//> using lib "com.lihaoyi::os-lib:0.8.1"
+println(os.pwd)
+```
+
+## `scala test` example
+```scala test
+//> using lib "org.scalameta::munit:0.7.29"
+
+class Test extends munit.FunSuite {
+  test("foo") {
+    assert(true)
+    println("Hello from tests")
+  }
+}
+```
+## Relying on directives from other snippets
+Directives from other snippets apply to the whole context.
+As a result, nothing really stops you from using a dependency
+from an earlier code block.
+```scala
+Printer.printHello()
+pprint.pprintln("world")
+```
+````
+
+:::note
+`scala` snippets inside of a Markdown input are not isolated. Each `using` directive applies to the whole project's
+context. A directive defined in a later snippet within the same source may override another defined in an earlier one.
+
+````markdown title="OverriddenDirective.md"
+## 1
+
+```scala
+//> using scala "2.12.17"
+println(util.Properties.versionNumberString)
+```
+
+## 2
+
+```scala
+//> using scala "2.13.10"
+println(util.Properties.versionNumberString)
+```
+````
+
+In this example, the directive from the second `scala` snippet will override the previous one and Scala `2.13.10` will
+be used for both.
+
+<ChainedSnippets>
+
+```bash ignore
+scala-cli OverriddenDirective.md
+```
+
+```text
+Compiling project (Scala 2.13.10, JVM)
+Compiled project (Scala 2.13.10, JVM)
+2.13.10
+2.13.10
+```
+
+</ChainedSnippets>
+
+:::
+
 ## Referring to code from Markdown
 
 ### Plain `scala` code blocks
 
-Referring to code from plain `scala` snippets in Markdown requires using their package name.
+Referring to code from plain `scala` snippets in markdown requires using their package name.
 Similarly to scripts, the package is inferred based on the relative path to the source file in your project.
 
 You also have to point to the Scope under which the code is located.

website/docs/guides/piping.md

@@ -29,7 +29,8 @@ The available options are as follows:
 
 - for standard Scala code use `_`, `_.scala` or `-.scala`;
 - for Scala scripts use `-`, `_.sc` or `-.sc`;
-- for Java code use `_.java` or `-.java`.
+- for Java code use `_.java` or `-.java`;
+- for Markdown code use `_.md` or `-.md`.
 
 ## Examples
 
@@ -75,6 +76,23 @@ Hello
 
 </ChainedSnippets>
 
+- Markdown code (experimental)
+
+<ChainedSnippets>
+
+```bash
+echo '# Example Snippet
+```scala
+println("Hello")
+```' | scala-cli _.md
+```
+
+```text
+Hello
+```
+
+</ChainedSnippets>
+
 ## Mixing piped sources with on-disk ones
 
 It is also possible to pipe some code via standard input, while the rest of your code is on-disk.