Update documentation of shebang command and scripts

website/docs/commands/shebang.md

@@ -6,6 +6,10 @@ sidebar_position: 30
 This command is equivalent to `run`, but it changes the way Scala CLI parses options (used to configure the tool) and
 inputs (the sources of your project) in order to be compatible with `shebang` scripts.
 
+The command `shebang` also allows script files to be executed even if they have no file extension,
+provided they start with the [`shebang` header](../guides/shebang.md#shebang-script-headers).
+Note that those files are always run as scripts even though they may contain e.g. valid `.scala` program.
+
 Normally, inputs and `scala-cli` options can be mixed. Program arguments (to be passed to your app) have to be specified
 after `--` (double dash) separator.
 

website/docs/guides/scripts.md

@@ -140,6 +140,10 @@ It is also possible to set `scala-cli` command-line options in the shebang line,
 #!/usr/bin/env -S scala-cli shebang --scala-version 2.13
 ```
 
+The command `shebang` also allows script files to be executed even if they have no file extension,
+provided they start with the [`shebang` header](../guides/shebang.md#shebang-script-headers).
+Note that those files are always run as scripts even though they may contain e.g. valid `.scala` program.
+
 ### Arguments
 
 You may also pass arguments to your script, and they are referenced with the special `args` variable:

website/docs/guides/shebang.md

@@ -19,7 +19,7 @@ println(args.size)
 println(args.headOption)
 ```
 
-And it works almost correctly.
+And it works correctly:
 
 <ChainedSnippets>
 
@@ -40,7 +40,7 @@ None
 
 </ChainedSnippets>
 
-And it also works.
+And it also works:
 
 <ChainedSnippets>
 
@@ -173,4 +173,63 @@ world: not found
 world: not found
 -->
 
+</ChainedSnippets>
+
+### Script files' extensions
+
+When running the `shebang` subcommand, script files don't need the `.sc` extension,
+but they are then REQUIRED to start with a shebang line:
+
+```scala title=hello-with-shebang
+#!/usr/bin/env -S scala-cli shebang -S 3
+
+println(args.size)
+println(args.headOption)
+```
+
+<ChainedSnippets>
+
+```bash
+chmod +x hello-with-shebang
+./hello-with-shebang Hello World
+```
+
+```text
+2
+Some(Hello)
+```
+<!-- Expected:
+2
+Some(Hello)
+-->
+
+</ChainedSnippets>
+
+```scala title=hello-no-shebang
+println(args.size)
+println(args.headOption)
+```
+
+<ChainedSnippets>
+
+```bash
+chmod +x hello-no-shebang
+./hello-no-shebang Hello World
+```
+
+```text
+hello-no-shebang does not contain shebang header
+possible fixes:
+  Add '#!/usr/bin/env scala-cli shebang' to the top of the file
+  Add extension to the file's name e.q. '.sc'
+```
+<!-- Expected:
+hello-no-shebang does not contain shebang header
+possible fixes:
+  Add '#!/usr/bin/env scala-cli shebang' to the top of the file
+  Add extension to the file's name e.q. '.sc'
+-->
+
+Note that files with no extensions are always run as scripts even though they may contain e.g. valid `.scala` program.
+
 </ChainedSnippets>