feat: move to mkdocs with all documentation (#435)

Move to MkDocs

- [x]: All pixi documentation is in mkdocs
- [x]: Setup ci stage to test the build of the docs
- [ ]: Use [mkdocs material insiders
program](https://squidfunk.github.io/mkdocs-material/insiders/#how-to-become-a-sponsor)
- [x]: Start a FAQ

.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'mkdocs.yml'
+
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    # Don't run on forks
+    if: github.repository == 'prefix-dev/pixi'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+
+      - uses: prefix-dev/setup-pixi@v0.3.0
+        with:
+          pixi-version: v0.6.0
+          cache: true
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+
+      - name: Build pixi Documentation
+        run: pixi run build-docs
+
+      #  This adds the following:
+      #   - A .nojekyll file to disable Jekyll GitHub Pages builds.
+      - name: Finalize documentation
+        run: |
+          touch site/.nojekyll
+
+      # https://github.com/actions/upload-pages-artifact#file-permissions
+      - run: chmod -c -R +rX site/
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v2
+        with:
+          path: "site"
+
+  deploy:
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.repository == 'prefix-dev/pixi' && github.ref == 'refs/heads/main'
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v2

.gitignore

@@ -6,3 +6,4 @@ __pycache__
 **/**/.pixi
 **/**/.build
 .DS_store
+site/

docs/FAQ.md

@@ -0,0 +1,33 @@
+
+## What is the difference with `conda`, `mamba`, `poetry`, `pip`
+
+| Tool   | Installs python | Builds packages | Runs predefined tasks | Has lockfiles builtin | Fast | Use without python                                                     |
+|--------|-----------------|-----------------|-----------------------|-----------------------|------|------------------------------------------------------------------------|
+| Conda  | ✅               | ❌               | ❌                     | ❌                     | ❌    | ❌                                                                      |
+| Mamba  | ✅               | ❌               | ❌                     | ❌                     | ✅    | [✅](https://mamba.readthedocs.io/en/latest/user_guide/micromamba.html) |
+| Pip    | ❌               | ✅               | ❌                     | ❌                     | ❌    | ❌                                                                      |
+| Pixi   | ✅               | 🚧              | ✅                     | ✅                     | ✅    | ✅                                                                      |
+| Poetry | ❌               | ✅               | ❌                     | ✅                     | ❌    | ❌                                                                      |
+
+
+## Why the name `pixi`
+Starting with the name `prefix` we iterated until we had a name that was easy to pronounce, spell and remember.
+There also wasn't a cli tool yet using that name.
+Unlike `px`, `pex`, `pax`, etc.
+We think it sparks curiosity and fun, if you don't agree, I'm sorry, but you can always alias it to whatever you like.
+
+=== "Linux & macOS"
+    ```shell
+    alias not_pixi="pixi"
+    ```
+=== "Windows"
+    PowerShell:
+    ```powershell
+    New-Alias -Name not_pixi -Value pixi
+    ```
+
+## Where is `pixi build`
+**TL;DR**: It's coming we promise!
+
+`pixi build` is going to be the subcommand that can generate a conda package out of a pixi project.
+This requires a solid build tool which we're creating with [`rattler-build`](https://github.com/prefix-dev/rattler-build) which will be used as a library in pixi.

docs/advanced/advanced_tasks.mdx → docs/advanced/advanced_tasks.md

@@ -10,7 +10,7 @@ With pixi tasks, this should become much easier to do.
 
 Here are some quick examples
 
-```toml title="pixi.toml" showLineNumbers
+```toml title="pixi.toml"
 [tasks]
 # Commands as lists so you can also add documentation in between.
 configure = { cmd = [
@@ -57,7 +57,7 @@ pixi task add start ".build/bin/sdl_example" --depends-on build
 
 Results in the following lines added to the `pixi.toml`
 
-```toml title="pixi.toml" showLineNumbers
+```toml title="pixi.toml"
 [tasks]
 # Configures CMake
 configure = "cmake -G Ninja -S . -B .build"
@@ -92,7 +92,7 @@ pixi task alias style fmt lint
 
 Results in the following `pixi.toml`.
 
-```toml title="pixi.toml" showLineNumbers
+```toml title="pixi.toml"
 fmt = "ruff"
 lint = "pylint"
 style = { depends_on = ["fmt", "lint"] }
@@ -123,7 +123,7 @@ pixi task add bar "python bar.py" --cwd scripts
 ```
 
 This will add the following line to `pixi.toml`:
-```toml title="pixi.toml" showLineNumbers
+```toml title="pixi.toml"
 [tasks]
 bar = { cmd = "python bar.py", cwd = "scripts" }
 ```
@@ -155,30 +155,30 @@ Next to running actual executable like `./myprogram`, `cmake` or `python` the sh
 ### Syntax
 
 - **Boolean list:** use `&&` or `||` to separate two commands.
-  - `&&`: if the command before `&&` succeeds continue with the next command.
-  - `||`: if the command before `||` fails continue with the next command.
+    - `&&`: if the command before `&&` succeeds continue with the next command.
+    - `||`: if the command before `||` fails continue with the next command.
 - **Sequential lists:** use `;` to run two commands without checking if the first command failed or succeeded.
 - **Environment variables:**
-  - Set env variable using: `export ENV_VAR=value`
-  - Use env variable using: `$ENV_VAR`
-  - unset env variable using `unset ENV_VAR`
+    - Set env variable using: `export ENV_VAR=value`
+    - Use env variable using: `$ENV_VAR`
+    - unset env variable using `unset ENV_VAR`
 - **Shell variables:** Shell variables are similar to environment variables, but won’t be exported to spawned commands.
-  - Set them: `VAR=value`
-  - use them: `VAR=value && echo $VAR`
+    - Set them: `VAR=value`
+    - use them: `VAR=value && echo $VAR`
 - **Pipelines:** Use the stdout output of a command into the stdin a following command
-  - `|`: `echo Hello | python receiving_app.py`
-  - `|&`: use this to also get the stderr as input.
+    - `|`: `echo Hello | python receiving_app.py`
+    - `|&`: use this to also get the stderr as input.
 - **Command substitution:** `$()` to use the output of a command as input for another command.
-  - `python main.py $(git rev-parse HEAD)`
+    - `python main.py $(git rev-parse HEAD)`
 - **Negate exit code:** `! ` before any command will negate the exit code from 1 to 0 or visa-versa.
 - **Redirects:** `>` to redirect the stdout to a file.
-  - `echo hello > file.txt` will put `hello` in `file.txt` and overwrite existing text.
-  - `python main.py 2> file.txt` will put the `stderr` output in `file.txt`.
-  - `python main.py &> file.txt` will put the `stderr` **and** `stdout` in `file.txt`.
-  - `echo hello > file.txt` will append `hello` to the existing `file.txt`.
+    - `echo hello > file.txt` will put `hello` in `file.txt` and overwrite existing text.
+    - `python main.py 2> file.txt` will put the `stderr` output in `file.txt`.
+    - `python main.py &> file.txt` will put the `stderr` **and** `stdout` in `file.txt`.
+    - `echo hello > file.txt` will append `hello` to the existing `file.txt`.
 - **Glob expansion:** `*` to expand all options.
-  - `echo *.py` will echo all filenames that end with `.py`
-  - `echo **/*.py` will echo all filenames that end with `.py` in this directory and all descendant directories.
-  - `echo data[0-9].csv` will echo all filenames that have a single number after `data` and before `.csv`
+    - `echo *.py` will echo all filenames that end with `.py`
+    - `echo **/*.py` will echo all filenames that end with `.py` in this directory and all descendant directories.
+    - `echo data[0-9].csv` will echo all filenames that have a single number after `data` and before `.csv`
 
 More info in [`deno_task_shell` documentation](https://deno.land/manual@v1.35.0/tools/task_runner#task-runner).

docs/advanced/explain_info_command.mdx → docs/advanced/explain_info_command.md

@@ -73,7 +73,7 @@ It will re-download everything it needs the next time you install a project.
 
 ### Auth storage
 
-Check the [authentication documentation](./../authentication)
+Check the [authentication documentation](authentication.md)
 
 ### Cache size
 

docs/advanced/multi_platform_configuration.mdx → docs/advanced/multi_platform_configuration.md

@@ -4,12 +4,12 @@ title: Multi platform config
 description: Learn how to set up for different platforms/OS's
 ---
 
-[Pixi's vision](./../vision) includes being supported on all major platforms. Sometimes that needs some extra configuration to work well.
+[Pixi's vision](../vision.md) includes being supported on all major platforms. Sometimes that needs some extra configuration to work well.
 On this page, you will learn what you can configure to align better with the platform you are making your application for.
 
 Here is an example `pixi.toml` that highlights some of the features:
 
-```toml showLineNumbers title="pixi.toml"
+```toml title="pixi.toml"
 [project]
 # Default project info....
 # A list of platforms you are supporting with your package.
@@ -61,7 +61,7 @@ If you are targeting a specific platform in your target specifier that was not s
 
 It might happen that you want to install a certain dependency only on a specific platform, or you might want to use a different version on different platforms.
 
-```toml title="pixi.toml" showLineNumbers
+```toml title="pixi.toml"
 [dependencies]
 python = ">=3.8"
 
@@ -90,7 +90,7 @@ pixi add --build --platform osx-64 clang
 
 Which results in this.
 
-```toml title="pixi.toml" showlinenumbers
+```toml title="pixi.toml"
 [target.win-64.host-dependencies]
 posix = "1.0.0.*"
 
@@ -105,7 +105,7 @@ Generated activation scripts are often in this category, default scripts in unix
 
 To deal with this, you can define your activation scripts using the target definition.
 
-```toml title="pixi.toml" showlinenumbers
+```toml title="pixi.toml"
 [activation]
 scripts = ["setup.sh", "local_setup.bash"]
 

docs/basic_usage.mdx → docs/basic_usage.md

@@ -3,8 +3,7 @@ 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.
+Ensure you've got `pixi` set up. If running `pixi` doesn't show the help, see the [getting started](index.md) if it doesn't.
 
 ```shell
 pixi
@@ -25,7 +24,7 @@ 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
+```py title="hello_world.py"
 def hello():
     print("Hello World, to the new revolution in package management.")
 
@@ -60,11 +59,13 @@ exit
 ```
 
 You've just learned the basic features of pixi:
-1. adding a dependency.
+
+1. initializing a project
+2. 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!