Merge pull request #2612 from Gedochao/docs/clean-up-categories

Add a subcategories layer for guides & cookbooks

build.sc

@@ -1813,7 +1813,7 @@ object ci extends Module {
 
   def checkScalaVersions() = T.command {
     website.checkMainScalaVersions(os.pwd / "website" / "docs" / "reference" / "scala-versions.md")
-    website.checkScalaJsVersions(os.pwd / "website" / "docs" / "guides" / "scala-js.md")
+    website.checkScalaJsVersions(os.pwd / "website" / "docs" / "guides" / "advanced" / "scala-js.md")
   }
 }
 

website/docs/commands/basics.md

@@ -6,7 +6,7 @@ import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
 
 
 Scala CLI is a command line tool that executes a given sub-command on the inputs it’s provided with, using a
-given [configuration](/docs/guides/configuration.md) to produce a result.
+given [configuration](../guides/introduction/configuration.md) to produce a result.
 
 The most important sub-commands are:
 
@@ -44,11 +44,11 @@ Note that all of these input formats can be used alongside each other.
 Scala CLI accepts the following types of source code:
 
 - `.scala` files, containing Scala code
-- `.sc` files, containing Scala scripts (see more in the [Scripts guide](/docs/guides/scripts.md))
+- `.sc` files, containing Scala scripts (see more in the [Scripts guide](../guides/scripting/scripts.md))
 - `.java` files, containing Java code
-- `.md` files, containing Markdown code (experimental, see more in the [Markdown guide](/docs/guides/markdown.md))
+- `.md` files, containing Markdown code (experimental, see more in the [Markdown guide](../guides/power/markdown.md))
 - `.c` and `.h` files, containing C code (only as resources for Scala Native, see more in
-  the [Scala Native guide](/docs/guides/scala-native.md))
+  the [Scala Native guide](../guides/advanced/scala-native.md))
 - `.jar` files, (see more in the [Run docs](run#jar))
 
 The following example shows the simplest input format.
@@ -203,7 +203,7 @@ Hello
 
 </ChainedSnippets>
 
-More details in the [GitHub gists cookbook](/docs/cookbooks/gists.md).
+More details in the [GitHub gists cookbook](../cookbooks/introduction/gists.md).
 
 ### Zip archive
 
@@ -304,7 +304,7 @@ You can also pipe code to Scala CLI for execution:
 
   </ChainedSnippets>
 
-More details in the [Piping guide](/docs/guides/piping.md).
+More details in the [Piping guide](../guides/advanced/piping.md).
 
 ## Scala CLI version
 
@@ -407,4 +407,4 @@ about the start of compilation, and so on.
 
 Some particular warning logs can be suppressed, either for a particular command by passing an option or with a global
 config.
-More details can be found in the [verbosity guide](../guides/verbosity.md)
+More details can be found in the [verbosity guide](..//guides/advanced/verbosity.md)

website/docs/commands/compile.md

@@ -24,7 +24,7 @@ The `compile` command is useful if you want to check that your code compiles
 
 The most common `compile` options are shown below.
 For a full list of options, run `scala-cli compile --help`, or check the options linked in the
-[reference documentation](/docs/reference/commands.md#compile).
+[reference documentation](../reference/commands.md#compile).
 
 ## Test scope
 
@@ -67,7 +67,7 @@ Watching sources, press Ctrl+C to exit.
 ## Scala version
 
 Scala CLI uses the latest stable version of Scala which was tested in Scala CLI (see our list
-of [Supported Scala Versions](/docs/reference/scala-versions)). You can specify the Scala version you'd like to use
+of [Supported Scala Versions](../reference/scala-versions)). You can specify the Scala version you'd like to use
 with `--scala`:
 
 ```bash
@@ -115,7 +115,7 @@ For compiling with a specific nightly build you have the full version:
 scala-cli Hello.scala -S 2.13.9-bin-4505094
 ```
 
-For setting this inside scala files, use [`using` directives](/docs/guides/using-directives.md):
+For setting this inside scala files, use [`using` directives](../guides/introduction/using-directives.md):
 
 ```scala compile
 //> using scala 2.nightly
@@ -139,15 +139,15 @@ scala-cli compile Hello.scala \
 ```
 
 Note that `--dependency` is only meant as a convenience. You should favor
-adding dependencies in the source files themselves via [`using` directives](/docs/guides/configuration.md#special-imports).
+adding dependencies in the source files themselves via [`using` directives](../guides/introduction/configuration.md#special-imports).
 
 You can also add simple JAR files — those that don’t have transitive dependencies — as dependencies, with `--jar`:
 
 ```bash
 scala-cli compile Hello.scala --jar /path/to/library.jar
 ```
 
-See the [Dependency management](/docs/guides/dependencies.md) guide for more details.
+See the [Dependency management](../guides/introduction/dependencies.md) guide for more details.
 
 ## Scala compiler options
 
@@ -474,7 +474,7 @@ line parameter `--exclude` along with a pattern:
 :::note
 The `exclude` directive should be placed in your `project.scala` file, which Scala CLI uses to determine the project
 root directory.
-For more details on `project.file`, see [the `Project root directory` reference](/docs/reference/root-dir).
+For more details on `project.file`, see [the `Project root directory` reference](../reference/root-dir).
 :::
 
 For example, to exclude all files in the `example/scala` directory, add the following directive to your

website/docs/commands/fmt.md

@@ -162,13 +162,13 @@ At the beginning `fmt` looks for the configuration inside the file specified in
 3. Configuration file is not found.
 
 - In the **first** case `fmt` uses the found `.scalafmt.conf` file to run `scalafmt`.
-- In the **second** case `fmt` creates a `.scalafmt.conf` file inside the `.scala-build` directory. Content of the previously found file is copied into the newly created file, missing parameters are [inferred](/docs/commands/fmt#scalafmt-version-and-dialect) and written into the same file. Created file is used to run `scalafmt`. 
-- In the **third** case `fmt` creates a `.scalafmt.conf` file inside the `.scala-build` directory, writes [inferred](/docs/commands/fmt#scalafmt-version-and-dialect) version and dialect into it and uses it to run `scalafmt`.
+- In the **second** case `fmt` creates a `.scalafmt.conf` file inside the `.scala-build` directory. Content of the previously found file is copied into the newly created file, missing parameters are [inferred](#scalafmt-version-and-dialect) and written into the same file. Created file is used to run `scalafmt`. 
+- In the **third** case `fmt` creates a `.scalafmt.conf` file inside the `.scala-build` directory, writes [inferred](#scalafmt-version-and-dialect) version and dialect into it and uses it to run `scalafmt`.
 
 If the `--save-scalafmt-conf` option is passed, then `fmt` command behaves as follows:
 - In the **first** case `fmt` uses the found `.scalafmt.conf` file to run `scalafmt`.
-- In the **second** case `fmt` [infers](/docs/commands/fmt#scalafmt-version-and-dialect) missing parameters, writes them directly into the previously found file and then uses this file to run `scalafmt`.
-- In the **third** case `fmt` creates a `.scalafmt.conf` file in the current workspace directory, writes [inferred](/docs/commands/fmt#scalafmt-version-and-dialect) version and dialect into it and uses it to run `scalafmt`.
+- In the **second** case `fmt` [infers](#scalafmt-version-and-dialect) missing parameters, writes them directly into the previously found file and then uses this file to run `scalafmt`.
+- In the **third** case `fmt` creates a `.scalafmt.conf` file in the current workspace directory, writes [inferred](#scalafmt-version-and-dialect) version and dialect into it and uses it to run `scalafmt`.
 
 :::note
 If the configuration is passed in the `--scalafmt-conf-str` option, Scala CLI will behave exactly the same as if it found the specified configuration in a `.scalafmt.conf` file in the workspace.

website/docs/commands/misc/bloop.md

@@ -25,7 +25,7 @@ The default location of the file is `.scala-build/bloop/project_name.json`.
 
 The last thing before launching the server is downloading its artifacts from Maven Central via Coursier if they are not already present in the local cache.
 :::tip
-When working in an environment with restricted access to the web, using Bloop can be disabled with the `--server=false` flag. Also, see the [section about the Offline mode](../../guides/offline.md).
+When working in an environment with restricted access to the web, using Bloop can be disabled with the `--server=false` flag. Also, see the [section about the Offline mode](../../guides/power/offline.md).
 :::
 
 Bloop is started as a separate JVM process, parameters of this process can be configured using arguments passed to the invoked subcommand ([see compilation server options](../../reference/cli-options.md#compilation-server-options)).

website/docs/commands/misc/pgp.md

@@ -35,7 +35,7 @@ Wrote public key e259e7e8a23475b3 to key.pub
 Wrote secret key to key.skr
 ```
 
-See [the dedicated page](docs/reference/password-options.md) for the various formats
+See [the dedicated page](../../reference/password-options.md) for the various formats
 accepted by the `--password` option.
 
 ## Get the fingerprint of a public key

website/docs/commands/package.md

@@ -443,7 +443,7 @@ scala-cli --power package --msi --output path.msi Hello.scala
 
 ## Using directives
 
-Instead of passing the `package` options directly from bash, it is possible to pass some of them with [using directives](/docs/guides/using-directives).
+Instead of passing the `package` options directly from bash, it is possible to pass some of them with [using directives](../guides/introduction/using-directives).
 
 ### packaging.packageType
 

website/docs/commands/repl.md

@@ -50,7 +50,7 @@ Bye!
 
 </ChainedSnippets>
 
-The `repl` command accepts the same arguments as the [compile](./compile.md) command. It first compiles any provided sources, and then exposes those results and any provided dependencies to the REPL session:
+The `repl` command accepts the same arguments as the [compile](compile.md) command. It first compiles any provided sources, and then exposes those results and any provided dependencies to the REPL session:
 
 ```scala title=mylibrary/Messages.scala
 package mylibrary

website/docs/commands/run.md

@@ -242,7 +242,7 @@ It is also possible to achieve it using `--platform` option:
 scala-cli Hello.scala --platform js
 ```
 
-See our dedicated [Scala.js guide](/docs/guides/scala-js.md) for more information.
+See our dedicated [Scala.js guide](../guides/advanced/scala-js.md) for more information.
 
 ## Scala Native
 
@@ -261,7 +261,7 @@ It is also possible to achieve it using `--platform` option:
 scala-cli Hello.scala --platform native
 ```
 
-We have a dedicated [Scala Native guide](/docs/guides/scala-native.md) as well.
+We have a dedicated [Scala Native guide](../guides/advanced/scala-native.md) as well.
 
 ## Platform
 
@@ -297,7 +297,7 @@ Hello world from scala script
 
 </ChainedSnippets>
 
-Our [scripts guide](/docs/guides/scripts.md) provides many more details.
+Our [scripts guide](../guides/scripting/scripts.md) provides many more details.
 
 ## Scala CLI from docker
 

website/docs/commands/shebang.md

@@ -7,7 +7,7 @@ This command is equivalent to `run`, but it changes the way Scala CLI parses opt
 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).
+provided they start with the [`shebang` header](../guides/scripting/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
@@ -24,5 +24,5 @@ the input, while everything after the input is considered a program argument.
 scala-cli shebang [scala_cli_options]... input [program_arguments]...
 ```
 
-More details can be found in [Shebang guide](/docs/guides/shebang).
+More details can be found in [Shebang guide](../guides/scripting/shebang).
 

website/docs/commands/test.md

@@ -10,8 +10,8 @@ Test sources are compiled separately (after the 'main' sources), and may use dif
 and other configurations.
 
 By default, all command line options apply to both the main and test sources,
-so [using directives](/docs/guides/using-directives.md) (
-or [special imports](/docs/guides/configuration#special-imports)) can be used to provide test-specific configurations.
+so [using directives](../guides/introduction/using-directives.md) (
+or [special imports](../guides/introduction/configuration#special-imports)) can be used to provide test-specific configurations.
 
 ## Test sources
 
@@ -88,7 +88,7 @@ the `test.dep` directive:
 ```
 
 For more details on test directives,
-see [the `using` directives guide](../guides/using-directives.md#directives-with-a-test-scope-equivalent).
+see [the `using` directives guide](../guides/introduction/using-directives.md#directives-with-a-test-scope-equivalent).
 
 ## Test framework
 

website/docs/cookbooks/ide/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "IDE",
+  "position": 20
+}

website/docs/cookbooks/intellij-multi-bsp.md → website/docs/cookbooks/ide/intellij-multi-bsp.md

@@ -3,7 +3,7 @@ title: Setup multiple projects in IDEA IntelliJ as separate modules
 sidebar_position: 13
 ---
 
-import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+import {ChainedSnippets} from "../../../src/components/MarkdownComponents.js";
 
 If you've read through [the basic IDEA IntelliJ cookbook](intellij.md), then you already know how to import a Scala CLI
 project using `BSP`. However, in some cases importing a single project just does not fit the bill.

website/docs/cookbooks/intellij-sbt-with-bsp.md → website/docs/cookbooks/ide/intellij-sbt-with-bsp.md

@@ -3,7 +3,7 @@ title: Scala CLI project in IntelliJ alongside your existing SBT project
 sidebar_position: 12
 ---
 
-import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+import {ChainedSnippets} from "../../../src/components/MarkdownComponents.js";
 
 If you've read through [the basic IDEA IntelliJ cookbook](intellij.md), then you already know how to import a Scala CLI
 project using `BSP`. However, did you know that it's possible to import one alongside an `SBT` project? (Or any other

website/docs/cookbooks/intellij.md → website/docs/cookbooks/ide/intellij.md

@@ -3,7 +3,7 @@ title: IntelliJ IDEA setup
 sidebar_position: 11
 ---
 
-import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+import {ChainedSnippets} from "../../../src/components/MarkdownComponents.js";
 
 It is possible to import a Scala CLI project into IDEA IntelliJ. The import is done
 through [BSP](https://build-server-protocol.github.io/) and the relevant files can be seen in the hidden `.bsp`

website/docs/cookbooks/intro.md

@@ -1,5 +1,5 @@
 ---
-title: Introduction
+title: Index
 sidebar_position: 1
 ---
 
@@ -8,31 +8,31 @@ sidebar_position: 1
 This section of the documentation contains a set of recipes that show how to use Scala CLI in particular situations.
 The recipes are intended to provide a solution to the task at hand, but also without going into great detail.
 
-For a more in-depth analysis, please check out our [Guides](/docs/guides/intro.md).
+For a more in-depth analysis, please check out our [Guides](../guides/intro.md).
 
 To get started, try one of the cookbooks below:
 
 ## Introductory cookbooks
 
-- [Picking the Scala version](./scala-versions.md)
-- [Picking the Java version](./scala-jvm)
-- [Debugging with Scala CLI](./debugging.md)
-- [Filter the test suites to run](./test-only.md)
-- [Running scripts](./scala-scripts.md)
-- [Scripts with instant startup](instant-startup-scala-scripts.md)
-- [Sharing and testing code with GitHub gists](./gists.md)
-- [Use Scala CLI in GitHub Actions](./gh-action.md)
+- [Picking the Scala version](introduction/scala-versions.md)
+- [Picking the Java version](introduction/scala-jvm.md)
+- [Debugging with Scala CLI](introduction/debugging.md)
+- [Filter the test suites to run](introduction/test-only.md)
+- [Running scripts](introduction/scala-scripts.md)
+- [Scripts with instant startup](introduction/instant-startup-scala-scripts.md)
+- [Sharing and testing code with GitHub gists](introduction/gists.md)
+- [Use Scala CLI in GitHub Actions](introduction/gh-action.md)
 
 ## Working with Scala CLI in IDEs
 
-- [Metals with VS Code](vscode.md)
-- [IDEA IntelliJ](intellij.md)
-- [Scala CLI alongside SBT in IDEA IntelliJ](intellij-sbt-with-bsp.md)
-- [Multiple Scala CLI projects as separate modules in IDEA IntelliJ](intellij-multi-bsp.md)
-- [Scala CLI within Emacs](emacs.md)
+- [Metals with VS Code](ide/vscode.md)
+- [IDEA IntelliJ](ide/intellij.md)
+- [Scala CLI alongside SBT in IDEA IntelliJ](ide/intellij-sbt-with-bsp.md)
+- [Multiple Scala CLI projects as separate modules in IDEA IntelliJ](ide/intellij-multi-bsp.md)
+- [Scala CLI within Emacs](ide/emacs.md)
 
 ## Packaging ⚡️
 
-- [Packaging Scala applications as executable files](scala-package.md)
-- [Packaging Scala applications as Docker images](scala-docker.md)
-- [Packaging Scala applications as GraalVM native images](native-images.md)
+- [Packaging Scala applications as executable files](package/scala-package.md)
+- [Packaging Scala applications as Docker images](package/scala-docker.md)
+- [Packaging Scala applications as GraalVM native images](package/native-images.md)

website/docs/cookbooks/introduction/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "position": 1
+}

website/docs/cookbooks/gists.md → website/docs/cookbooks/introduction/gists.md

@@ -3,7 +3,7 @@ title: GitHub gists
 sidebar_position: 8
 ---
 
-import {ChainedSnippets} from "../../src/components/MarkdownComponents.js";
+import {ChainedSnippets} from "../../../src/components/MarkdownComponents.js";
 
 ## Running code from gists
 
@@ -116,4 +116,4 @@ Hello
 
 </ChainedSnippets>
 
-You can find more information on working with Markdown in the [Markdown guide](/docs/guides/markdown.md).
+You can find more information on working with Markdown in the [Markdown guide](../../guides/power/markdown.md).

website/docs/cookbooks/instant-startup-scala-scripts.md → website/docs/cookbooks/introduction/instant-startup-scala-scripts.md

@@ -3,7 +3,7 @@ title: Scripts with instant startup
 sidebar_position: 7
 ---
 
-import {ChainedSnippets, GiflikeVideo} from "../../src/components/MarkdownComponents.js";
+import {ChainedSnippets, GiflikeVideo} from "../../../src/components/MarkdownComponents.js";
 
 Scala CLI allows to easly compile and run Scala Scripts.
 It also allows for straightforward compilation with Scala Native. 

website/docs/cookbooks/scala-versions.md → website/docs/cookbooks/introduction/scala-versions.md

@@ -3,7 +3,7 @@ title: Picking the Scala version
 sidebar_position: 2
 ---
 
-By default, Scala CLI runs the latest supported scala version. See our list of [Supported Scala Versions](/docs/reference/scala-versions) in Scala CLI.
+By default, Scala CLI runs the latest supported scala version. See our list of [Supported Scala Versions](../../reference/scala-versions) in Scala CLI.
 
 To demonstrate how this works, here’s a universal piece of code that detects the Scala version at runtime.
 The code is a bit complicated, so we suggest that you skip reading the whole file, and just focus on what it prints:
@@ -121,7 +121,7 @@ Scala: 2\.13\.10
 -->
 
 :::note
-See our [Using Directives Guide](/docs/guides/using-directives.md) for more details on `using` directives.
+See our [Using Directives Guide](../../guides/introduction/using-directives.md) for more details on `using` directives.
 :::
 
 

website/docs/cookbooks/package/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Packaging ⚡",
+  "position": 30
+}

website/docs/cookbooks/native-images.md → website/docs/cookbooks/package/native-images.md

@@ -1,5 +1,5 @@
 ---
-title: Packaging as GraalVM native images
+title: Packaging as GraalVM native images ⚡
 sidebar_position: 16
 ---
 

website/docs/cookbooks/scala-docker.md → website/docs/cookbooks/package/scala-docker.md

@@ -1,5 +1,5 @@
 ---
-title: Packaging as Docker images
+title: Packaging as Docker images ⚡
 sidebar_position: 15
 ---
 

website/docs/cookbooks/scala-package.md → website/docs/cookbooks/package/scala-package.md

@@ -1,5 +1,5 @@
 ---
-title: Packaging as executable files
+title: Packaging as executable files ⚡
 sidebar_position: 14
 ---