docs: copy from cms (#355)

depends on https://github.com/prefix-dev/cms/pull/10

6 files changed, 608 insertions, 39 deletions

diff --git a/docs/basic_usage.mdx b/docs/basic_usage.mdx
new file mode 100644
index 0000000..190674d
--- /dev/null
+++ b/docs/basic_usage.mdx
@@ -0,0 +1,89 @@
+---
+part: pixi
+title: Basic usage
+description: Taking your first steps with pixi
+---
+
+Make sure that you have `pixi` installed, this should print the help function, check the [installation manual](overview) if it doesn't.
+
+```shell
+pixi
+```
+
+Initialize a new project and navigate to the project directory.
+
+```shell
+pixi init pixi-hello-world
+cd pixi-hello-world
+```
+
+Add the dependencies you would like to use.
+
+```shell
+pixi add python
+```
+
+Create a file named `hello_world.py` in the directory and paste the following code into the file.
+
+```python title="hello_world.py" showLineNumbers
+def hello():
+    print("Hello World, to the new revolution in package management.")
+
+if __name__ == "__main__":
+    hello()
+```
+
+Run the code inside the environment.
+
+```shell
+pixi run python hello_world.py
+```
+
+You can also put this run command in a **task**.
+
+```shell
+pixi task add hello python hello_world.py
+```
+
+After adding the task, you can run the task using its name.
+
+```shell
+pixi run hello
+```
+
+Use the `shell` command to activate the environment and start a new shell in there.
+
+```shell
+pixi shell
+python
+exit
+```
+
+You've just learned the basic features of pixi:
+1. adding a dependency.
+2. adding a task, and executing it.
+3. running a program.
+Feel free to play around with what you just learned like adding more tasks, dependencies or code.
+If you want to learn more checkout out our [in-depth documentation](./advanced)
+
+Happy coding!
+
+## Use pixi as an installation tool
+
+Use pixi to install tools on your machine.
+
+Some notable examples:
+
+```shell
+# Awesome cross shell prompt, huge tip when using pixi!
+pixi global install starship
+
+# Want to try a different shell?
+pixi global install fish
+
+# Install other prefix.dev tools
+pixi global install rattler-build
+
+# Install a linter you want to use in multiple projects.
+pixi global install ruff
+```
diff --git a/docs/cli.mdx b/docs/cli.mdx
index 7780c15..0b8dd81 100644
--- a/docs/cli.mdx
+++ b/docs/cli.mdx
@@ -85,9 +85,11 @@ pixi run --manifest-path ~/myproject/pixi.toml python
 pixi run build
 ```
 
-> **Note:** In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the run command.
-> Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands.
-> This is done so that the run commands can be run across all platforms.
+:::info
+In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the run command.
+Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands.
+This is done so that the run commands can be run across all platforms.
+:::
 
 ## `task`
 
@@ -142,9 +144,11 @@ cow = "cowpy \"Hello User\""
 moo = { depends_on = ["cow"] }
 ```
 
-> **Note:** In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the tasks.
-> Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands.
-> This is done so that the tasks defined can be run across all platforms.
+:::info
+In `pixi` the [`deno_task_shell`](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) is the underlying runner of the tasks.
+Checkout their [documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner) for the syntax and available commands.
+This is done so that the tasks defined can be run across all platforms.
+:::
 
 ## `shell`
 
@@ -194,7 +198,9 @@ This command is used to authenticate the user's access to remote hosts such as `
 
 Store authentication information for given host.
 
-> **Note:** The host is real hostname not a channel.
+:::tip
+The host is real hostname not a channel.
+:::
 
 #### Options
 
@@ -221,7 +227,12 @@ pixi auth logout repo.prefix.dev
 pixi auth logout anaconda.org
 ```
 
-## `global install`
+## `global`
+
+Global is the main entry point for the part of pixi that executes on the
+global(system) level.
+
+### `global install`
 
 This command installs a package into its own environment and adds the binary to `PATH`, allowing you to access it anywhere on your system without activating the environment.
 
@@ -245,6 +256,39 @@ pixi global install python=3.11.0=h10a6764_1_cpython
 
 After using global install, you can use the package you installed anywhere on your system.
 
+### `global info`
+
+This command shows the current installed global environments including what binaries come with it.
+A global installed package/environment can possibly contain multiple binaries.
+Here is an example of a few installed packages:
+```
+> pixi global info
+Globally installed binary packages:
+  -  [package] starship
+     -  [bin] starship
+  -  [package] pre-commit
+     -  [bin] pre-commit
+  -  [package] grayskull
+     -  [bin] grayskull
+     -  [bin] greyskull
+     -  [bin] conda-grayskull
+     -  [bin] conda-greyskull
+  -  [package] zsh
+     -  [bin] zsh
+     -  [bin] zsh-5
+```
+
+### `global remove`
+
+Removes a package previously installed into a globally accessible location via
+`pixi global install`
+
+Use `pixi global info` to find out what the package name is that belongs to the tool you want to remove.
+
+```
+pixi global remove pre-commit
+```
+
 ## `project`
 
 This subcommand allows you to modify the project configuration through the command line interface.
diff --git a/docs/configuration.mdx b/docs/configuration.mdx
new file mode 100644
index 0000000..dd4fc11
--- /dev/null
+++ b/docs/configuration.mdx
@@ -0,0 +1,336 @@
+---
+part: pixi
+title: Configuration
+description: Learn what you can do in the `pixi.toml` configuration.
+---
+
+The `pixi.toml` is the pixi project configuration file, also known as the project manifest.
+
+A `toml` file is structured in different tables.
+This document will explain the usage of the different tables.
+For more technical documentation check [crates.io](https://docs.rs/pixi/latest/pixi/project/manifest/struct.ProjectManifest.html).
+
+## The `project` table
+The minimally required information in the `project` table is:
+```toml
+[project]
+name = "project-name"
+version = "0.1.0"
+authors = ["John Doe <j.doe@prefix.dev>"]
+channels = ["conda-forge"]
+platforms = ["linux-64"]
+```
+
+### `name`
+The name of the project.
+```toml
+[project]
+name = "project-name"
+```
+
+### `version`
+The version of the project.
+This should be a valid version based on the conda Version Spec.
+See the [version documentation](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html), for an explanation what is allowed in a Version Spec.
+```toml
+[project]
+version = "1.2.3"
+```
+
+### `authors`
+This is a list of authors of the project.
+```toml
+[project]
+authors = ["John Doe <j.doe@prefix.dev>", "Marie Curie <mss1867@gmail.com>"]
+```
+
+### `channels`
+This is a list that defines the channels used to fetch the packages from.
+If you want to use channels hosted on `anaconda.org` you only need to use the name of the channel directly.
+```toml
+[project]
+channels = ["conda-forge", "robostack", "bioconda", "nvidia", "pytorch"]
+```
+
+Channels situated on the file system are also supported with file paths:
+```toml
+[project]
+channels = ["conda-forge", "file:///home/user/staged-recipes/build_artifacts"]
+```
+
+To access private or public channels on [prefix.dev](prefix.dev) or [Quetz](https://github.com/mamba-org/quetz) use the url including the hostname:
+```toml
+[project]
+channels = ["conda-forge", "https://repo.prefix.dev/channel-name"]
+```
+
+### `platforms`
+Defines the list of platforms that the project supports.
+Pixi solves the dependencies for all these platforms and puts them in the lockfile (`pixi.lock`).
+
+```toml
+[project]
+platforms = ["win-64", "linux-64", "osx-64", "osx-arm64"]
+```
+The available platforms are listed here: [link](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/enum.Platform.html)
+
+### `description` (optional)
+Should contain a short description of the project.
+```toml
+[project]
+description = "A simple description"
+```
+
+### `license` (optional)
+The license as a valid [SPDX](https://spdx.org/licenses/) string (e.g. MIT AND Apache-2.0)
+```toml
+[project]
+license = "MIT"
+```
+
+### `license-file` (optional)
+Relative path to the license file.
+```toml
+[project]
+license-file = "LICENSE.md"
+```
+
+### `readme` (optional)
+Relative path to the README file.
+```toml
+[project]
+readme = "README.md"
+```
+
+### `homepage` (optional)
+URL of the project homepage.
+```toml
+[project]
+homepage = "https://pixi.sh"
+```
+
+### `repository` (optional)
+URL of the project source repository.
+```toml
+[project]
+repository = "https://github.com/prefix-dev/pixi"
+```
+
+### `documentation`
+URL of the project documentation.
+```toml
+[project]
+documentation = "https://pixi.sh"
+```
+
+## The `tasks` table
+Tasks are a way to automate certain custom commands in your project.
+For example: a `lint` or `format` step.
+Tasks in a pixi project are essentially cross-platform shell commands, with a unified syntax across platforms.
+For the more in-depth information check the [Advanced tasks documentation](advanced/advanced_tasks).
+Pixi tasks are run in a pixi environment using `pixi run` and are executed using the [`deno_task_shell`](advanced/advanced_tasks#our-task-runner-deno_task_shell).
+
+```toml
+[tasks]
+simple = "echo This is a simple task"
+cmd = { cmd="echo Same as a simple task but now more verbose"}
+depending = { cmd="echo run after simple", depends_on="simple"}
+alias = { depends_on=["depending"]}
+```
+You can modify this table using [`pixi task`](cli#task).
+:::note
+Specify different tasks for different platforms using the [target](#the-target-table) table
+:::
+
+## The `system-requirements` table
+The system requirements are used to define minimal system specifications used during dependency resolution.
+For example, we can define a unix system with a specific minimal libc version, this will be the minimal system specification for the project.
+System specifications are directly related to the [virtual packages](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-virtual.html).
+
+Currently, the specified **defaults** are the same as [conda-lock](https://github.com/conda/conda-lock)'s implementation:
+<Tabs groupId="Platforms">
+    <TabItem value="Linux">
+        ```toml title="default system requirements"
+        [system-requirements]
+        unix = true
+        linux = "5.10"
+        libc = { family="glibc", version="2.17" }
+        ```
+    </TabItem>
+    <TabItem value="Windows">
+        ```toml title="default system requirements"
+        [system-requirements]
+        windows = true
+        ```
+    </TabItem>
+    <TabItem value="Osx-64">
+        ```toml title="default system requirements"
+        [system-requirements]
+        unix = true
+        macos = "10.15"
+        ```
+    </TabItem>
+    <TabItem value="Osx-arm64">
+        ```toml title="Default system requirements"
+        [system-requirements]
+        unix = true
+        macos = "11.0"
+        ```
+    </TabItem>
+</Tabs>
+
+Only if a project requires a different set should you define them.
+
+For example, when installing environments on old versions of linux.
+You may encounter the following error:
+```
+× The current system has a mismatching virtual package. The project requires '__linux' to be at least version '5.10' but the system has version '4.12.14'
+```
+This suggests that the system requirements for the project should be lowered.
+To fix this, add the following table to your configuration:
+```
+[system-requirements]
+linux = "4.12.14"
+```
+
+## The `dependencies` table(s)
+This section defines what dependencies you would like to use your project.
+
+There are multiple dependencies tables.
+The default is `[dependencies]`, which are dependencies that are shared across platforms.
+
+Dependencies are defined using a [VersionSpec](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/version_spec/enum.VersionSpec.html).
+A `VersionSpec` combines a [Version](https://docs.rs/rattler_conda_types/latest/rattler_conda_types/struct.Version.html) with an optional operator.
+
+Some examples are:
+```toml
+# Use this exact package version
+package0 = "1.2.3"
+# Use 1.2.3 up to 1.3.0
+package1 = "~=1.2.3"
+# Use larger than 1.2 lower and equal to 1.4
+package2 = ">1.2,<=1.4"
+# Bigger or equal than 1.2.3 or lower not including 1.0.0
+package3 = ">=1.2.3|<1.0.0"
+```
+
+:::tip
+The dependencies can be easily added using the `pixi add` command line.
+Running `add` for an existing dependency will replace it with the newest it can use.
+:::
+:::note
+To specify different dependencies for different platforms use the [target](#the-target-table) table
+:::
+
+### `dependencies`
+Add any conda package dependency that you want to install into the environment.
+Don't forget to add the channel to the project table should you use anything different than `conda-forge`.
+
+```toml
+[dependencies]
+python = ">3.9,<=3.11"
+rust = "1.72"
+```
+
+:::note
+All packages added to the `dependencies` table are also included as dependencies of the binary build by `pixi build`.
+
+To only include certain packages in different stages of the build see [`build-dependencies`](#build-dependencies) and [`host-dependencies`](#host-dependencies).
+:::
+
+### `host-dependencies`
+
+This table contains dependencies that are needed to build your project but which should not be included when your project is installed as part of another project.
+In other words, these dependencies are available during the build but are no longer available when your project is installed.
+Dependencies listed in this table are installed for the architecture of the target machine.
+
+```toml
+[host-dependencies]
+python = "~=3.10.3"
+```
+
+Typical examples of host dependencies are:
+
+* Base interpreters: a Python package would list `python` here and an R package would list `mro-base` or `r-base`.
+* Libraries your project links against during compilation like `openssl`, `rapidjson`, or `xtensor`.
+
+### `build-dependencies`
+This table contains dependencies that are needed to build the project.
+Different from `dependencies` and `host-dependencies` these packages are installed for the architecture of the _build_ machine.
+This enables cross-compiling from one machine architecture to another.
+
+```toml
+[build-depencencies]
+cmake = "~=3.24"
+```
+
+Typical examples of build dependencies are:
+
+* Compilers are invoked on the build machine, but they generate code for the target machine.
+If the project is cross-compiled the architecture of the build and target machine might differ.
+* `cmake` is invoked on the build machine to generate additional code- or project-files which are then include in the compilation process.
+
+:::info
+The _build_ target refers to the machine that will execute the build.
+Programs and libraries installed by these dependencies will be executed on the build machine.
+
+For example, if you compile on a MacBook with an Apple Silicon chip but target Linux x86_64 then your *build* platform is `osx-arm64` and your *host* platform is `linux-64`.
+:::
+
+## The `activation` table
+If you want to run an activation script inside the environment when either doing a `pixi run` or `pixi shell` these can be defined here.
+The scripts defined in this table will be sourced when the environment is activated using `pixi run` or `pixi shell`
+
+```toml
+[activation]
+scripts = ["env_setup.sh"]
+```
+:::note
+Specify different scripts for different platforms using the [target](#the-target-table) table
+:::
+
+
+## The `target` table
+The target table is a table that allows for platform specific configuration.
+Allowing you to make different sets of tasks or dependencies per platform.
+
+The target table is currently implemented for the following sub-tables:
+- [`activation`](#the-activation-table)
+- [`dependencies`](#the-dependencies-table)
+- [`tasks`](#the-tasks-table)
+
+The target table is defined using `[target.PLATFORM.SUB-TABLE]`.
+E.g `[target.linux-64.dependencies]`
+The platform can be any of the target [platforms](#platforms) but must also be defined there.
+The sub-table can be any of the specified above.
+
+To make it a bit more clear, lets look at an example below.
+Currently, pixi combines the top level tables like `dependencies` with the target-specific ones into a single set.
+Which, in the case of dependencies, can both add or overwrite dependencies.
+In the example below, we have `cmake` being used for all targets but on `osx-64` a different version of python will be selected.
+```toml
+[dependencies]
+cmake = "3.26.4"
+python = "3.10"
+
+[target.osx-64.dependencies]
+python = "3.11"
+```
+
+Here are some more examples:
+```toml
+[target.win-64.activation]
+scripts = ["setup.ps1"]
+
+[target.win-64.dependencies]
+msmpi = "~=10.1.1"
+
+[target.win-64.build-dependecies]
+vs2022_win-64 = "19.36.32532"
+
+[target.win-64.tasks]
+tmp = "echo $TEMP"
+
+[target.osx-64.dependencies]
+clang = ">=16.0.6"
+```
diff --git a/docs/examples/cpp-sdl.mdx b/docs/examples/cpp-sdl.mdx
index 58c8f37..cd56025 100644
--- a/docs/examples/cpp-sdl.mdx
+++ b/docs/examples/cpp-sdl.mdx
@@ -23,7 +23,7 @@ Run the `start` command
 pixi run start
 ```
 
-Using the [`depends_on`](/advanced/advanced_tasks#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks.
+Using the [`depends_on`](../advanced/advanced_tasks#depends-on) feature you only needed to run the `start` task but under water it is running the following tasks.
 
 ```shell
 # Configure the CMake project
diff --git a/docs/overview.mdx b/docs/overview.mdx
index 52f20ca..f666175 100644
--- a/docs/overview.mdx
+++ b/docs/overview.mdx
@@ -1,43 +1,143 @@
 ---
-part: Overview
-title: Pixi
+part: pixi
+title: Getting Started
 description: Package management made easy
 ---
 
-Explore pixi's documentation to find how to get started, how its used and why we build it.
+Pixi is a package management tool for developers.
+It allows the developer to install libraries and applications a reproducible way.
+Use pixi cross-platform, on Windows, Mac and Linux.
+
+# Installation
+
+To install pixi you can run the following command in your terminal:
+
+<Tabs groupId="install_os">
+  <TabItem value="Linux & macOS">
+  ```bash
+  curl -fsSL https://pixi.sh/install.sh | bash
+  ```
+
+  The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `~/.pixi/bin`.
+  If this directory does not already exist, the script will create it.
+
+  The script will also update your `~/.bash_profile` to include `~/.pixi/bin` in your PATH, allowing you to invoke the `pixi` command from anywhere.
+
+  </TabItem>
+  <TabItem value="Windows">
+  ```shell
+  iwr -useb https://pixi.sh/install.ps1 | iex
+  ```
+
+  The above invocation will automatically download the latest version of `pixi`, extract it, and move the `pixi` binary to `LocalAppData/pixi/bin`.
+  If this directory does not already exist, the script will create it.
+
+  The command will also automatically add `LocalAppData/pixi/bin` to your path allowing you to invoke `pixi` from anywhere.
+
+  </TabItem>
+</Tabs>
+
+:::tip
+
+You might need to restart your terminal or source your shell for the changes to take effect.
+
+:::
+
+# Autocompletion
+
+To get autocompletion run:
+
+<Tabs groupId="install_os">
+    <TabItem value="Linux & macOS">
+        ```shell
+        # Pick your shell (use `echo $SHELL` to find the shell you are using.):
+        echo 'eval "$(pixi completion --shell bash)"' >> ~/.bashrc
+        echo 'eval "$(pixi completion --shell zsh)"' >> ~/.zshrc
+        echo 'pixi completion --shell fish | source' >> ~/.config/fish/config.fish
+        echo 'eval (pixi completion --shell elvish | slurp)' >> ~/.elvish/rc.elv
+        ```
+    </TabItem>
+    <TabItem value="Windows">
+        ```shell
+        Add-Content -Path $PROFILE -Value 'Invoke-Expression (&pixi completion --shell powershell)'
+        ```
+    </TabItem>
+</Tabs>
+
+And then restart the shell or source the shell config file.
+
+## Alternative installation methods
+
+Although we recommend installing pixi through the above method we also provide additional installation methods.
+
+### Homebrew
+
+Pixi is available via homebrew. To install pixi via homebrew simply run:
+
+```shell
+brew install pixi
+```
+
+### Windows installer
+
+We provide an `msi` installer on [our Github releases page](https://github.com/prefix-dev/pixi/releases/latest).
+The installer will download pixi and add it to the path.
+
+### Install from source
+
+pixi is 100% written in Rust and therefore it can be installed, build and
+tested with cargo.
+To start using pixi from a source build run:
+
+```shell
+cargo install --locked --git https://github.com/prefix-dev/pixi.git
+```
+
+or when you want to make changes use:
+
+```shell
+cargo build
+cargo test
+```
+
+If you have any issues building because of the dependency on `rattler` checkout
+it's [compile steps](https://github.com/mamba-org/rattler/tree/main#give-it-a-try)
+
+## Uninstall
+
+To uninstall pixi from you system, simply remove the binary.
+
+<Tabs groupId="install_os">
+  <TabItem value="Linux & macOS">
+  ```shell
+  rm ~/.pixi/bin/pixi
+  ```
+  </TabItem>
+  <TabItem value="Windows">
+  ```shell
+  $PIXI_BIN = "$Env:LocalAppData\pixi\bin\pixi"; Remove-Item -Path $PIXI_BIN
+  ```
+  </TabItem>
+</Tabs>
+
+After this command you can still use the tools you installed with pixi.
+To remove these as well just remove the whole `~/.pixi` directory and remove the directory from your path.
 
-<Cols3>
-  <DocLinkCard
-    link="/pixi/installation"
-    title="Installation"
-    excerpt="Install pixi on your machine."
-  ></DocLinkCard>
-  <DocLinkCard
-    link="/pixi/getting_started"
-    title="Getting started"
-    excerpt="Learn how to get started with pixi."
-  ></DocLinkCard>
-  <DocLinkCard
-    link={"/pixi/vision"}
-    title="Pixi Vision"
-    excerpt={"The vision of pixi"}
-  ></DocLinkCard>
-</Cols3>
 
 <Cols3>
   <DocLinkCard
-    link="/pixi/cli"
-    title="Commands"
-    excerpt="Shows the subcommands of pixi and its options."
+    link="/pixi/basic_usage"
+    title="Basic usage"
+    excerpt="Learn how to use pixi."
   ></DocLinkCard>
   <DocLinkCard
-    link="https://github.com/prefix-dev/pixi/tree/main/examples"
-    title="Examples"
-    excerpt="Shows some useful example projects on github."
+    link="/pixi/cli"
+    title="Command reference"
+    excerpt="Explains all available pixi subcommands."
   ></DocLinkCard>
   <DocLinkCard
-    link="/pixi/authentication"
-    title="Authentication"
-    excerpt="Shows how to deal with authentication in pixi."
+    link="/pixi/examples"
+    title="Example projects"
+    excerpt="See a few examples of projects run with pixi."
   ></DocLinkCard>
 </Cols3>
diff --git a/docs/vision.mdx b/docs/vision.mdx
index a78bfb6..9ff36c8 100644
--- a/docs/vision.mdx
+++ b/docs/vision.mdx
@@ -1,5 +1,5 @@
 ---
-part: Pixi Vision
+part: pixi
 title: Pixi Vision
 description: What is the vision for pixi?
 ---