docs: continue migration

fixes #339

CODE_OF_CONDUCT.md

@@ -0,0 +1,4 @@
+## Code of Conduct
+
+* Be kind to others ;
+* Critic code not people.

CONTRIBUTING.md

@@ -1,18 +1,23 @@
-# Contribution Guide
+## :+1: Contribute
 
-## Code of Conduct
+!!! info
 
-* Be kind to others ;
-* Critic code not people.
+    We use [`docker`](https://docs.docker.com/install/) to isolate from our working environment.
 
-## Release
+Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container:
 
-Note, we follow [semver](https://semver.org/), release is manage in the pipeline, see [RELEASE.md](./RELEASE.md)
+    make build-pure-on FISH_VERSION=3.3.1
+    make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish"
 
-## Code Conventions for `pure`
+## Code Conventions
 
-* Use the idiomatic [`test` instead of `[`](httpsc://fishshell.com/docs/current/commands.html#test) brackets (as recommended by the documentation).
-* Use **long form options**, _e.g._ `set --local`, as they are more explicit over cryptic 1-letter form.
+### Be Fishy
+
+Use the idiomatic [`test` instead of `[`](httpsc://fishshell.com/docs/current/commands.html#test) brackets (as recommended by the documentation).
+
+### Be Explicit
+
+Use **long form options**, _e.g._ `set --local`, as they are more explicit over cryptic 1-letter form.
 
 ### Naming Public Item
 
@@ -112,3 +117,5 @@ $pure_enable_git_async = false
 ```fish
 $pure_threshold_command_duration
 ```
+
+[fish-releases]: https://github.com/fish-shell/fish-shell/releases

docs/.pages

@@ -0,0 +1,4 @@
+nav:
+    - Documentation: .
+    - Contributing: contributing
+    - About: about

RELEASE.md → docs/RELEASE.md

@@ -1,8 +1,12 @@
-# Releasing
+## Releasing
 
 Release process is automated in the pipeline with the following steps.
 
-## Test
+!!! info
+
+    We follow [semver](https://semver.org/), release is manage in the pipeline
+
+### Test
 
 We run the test workflow on:
 
@@ -13,9 +17,11 @@ We run the test workflow on:
   * `**.fish` files with the exception `conf.d/pure.fish`, as we have dedicated mechanism to manage versions bump ;
   * and workflow (`*.yml`) files
 
-## Versioning
+### Versioning
+
+!!! success
 
-**required:** Commits must **[follow conventional commits convention][coco]**.
+    Commit messages must **[follow conventional commits convention][coco]**.
 
 Versioning is done automatically based on commit messages and triggered only on `master` branch.
 
@@ -25,10 +31,11 @@ Details:
 2. Then update `$pure_version` value in `./conf.d/pure.fish` ;
 3. Finally commit and [push the change][push] to the repo.
 
-## Adding new tag
+### Adding new tag
 
 The `add-version-tag.yml` pipeline is triggered only for `master` when `./conf.d/pure.fish` is changed and add a tagged based on `$pure_version`.
 
 [next-version]: https://github.com/thenativeweb/get-next-version
 [push]: https://github.com/ad-m/github-push-action
+<!-- markdownlint-disable-next-line MD053 -->
 [coco]: https://www.conventionalcommits.org/en/v1.0.0/

docs/about.md

@@ -0,0 +1,20 @@
+# About
+
+## :classical_building: License
+
+[MIT][MIT]
+
+## Contributors
+
+### :man_technologist: Maintainer
+
+* [Édouard Lopez](https://github.com/edouard-lopez)
+
+### :clap: Thanks
+
+* [@andreiborisov](https://github.com/andreiborisov) for the [docker images][docker-images] ;
+* [@jorgebucaran](https://github.com/jorgebucaran/) for [fishtape](https://github.com/jorgebucaran/fishtape) ;
+* [@rafaelrinaldi](https://github.com/pure-fish/pure) for starting the project ;
+
+[MIT]: ../LICENSE.md
+[docker-images]: https://github.com/andreiborisov/docker-fish/

docs/components/.pages

@@ -0,0 +1 @@
+hide: true

docs/components/colours.md

@@ -0,0 +1,22 @@
+!!! tip
+
+    See [`set_color`][fish-set-color] documentation for full possibilities.
+
+!!! info
+
+    The absence of `$` sign is expected in `pure_` named colours.
+
+| Base Color               | Inherited by                                                                                                                                                                                                        | Default   |
+| :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------- |
+| **`pure_color_danger`**  | **`pure_color_prompt_on_error`**                                                                                                                                                                                    | `red`     |
+| **`pure_color_dark`**    |                                                                                                                                                                                                                     | `black`   |
+| **`pure_color_info`**    | **`pure_color_git_unpulled_commits`**<br>**`pure_color_git_unpushed_commits`**                                                                                                                                      | `cyan`    |
+| **`pure_color_light`**   | **`pure_color_username_root`**                                                                                                                                                                                      | `white`   |
+| **`pure_color_mute`**    | **`pure_color_git_branch`**<br>**`pure_color_git_dirty`**<br>**`pure_color_git_stash`**<br>**`pure_color_hostname`**<br>**`pure_color_at_sign`**<br>**`pure_color_username_normal`**<br>**`pure_color_virtualenv`** | `brblack` |
+| **`pure_color_normal`**  | **`pure_color_jobs`**                                                                                                                                                                                               | `normal`  |
+| **`pure_color_primary`** | **`pure_color_current_directory`**                                                                                                                                                                                  | `blue`    |
+| **`pure_color_success`** | **`pure_color_prompt_on_success`**                                                                                                                                                                                  | `magenta` |
+| **`pure_color_warning`** | **`pure_color_command_duration`**                                                                                                                                                                                   | `yellow`  |
+
+<!-- markdownlint-disable MD053 -->
+[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html

docs/components/configuration.md

@@ -0,0 +1,7 @@
+
+You can tweak `pure` behavior and color by changing [universal variables](https://fishshell.com/docs/current/tutorial.html#tut_universal) either directly in the terminal or in your `config.fish`, _e.g._:
+
+```shell
+set --universal pure_show_system_time true
+set --universal pure_color_system_time pure_color_mute
+```

docs/components/features-list.md

@@ -0,0 +1,104 @@
+### Prompt Symbol
+
+| Option                   | Default | Description    |
+| :----------------------- | :------ | :------------- |
+| **`pure_symbol_prompt`** | `❯`     | Prompt symbol. |
+
+### Git
+
+| Option                                 | Default | Description                                          |
+| :------------------------------------- | :------ | :--------------------------------------------------- |
+| **`pure_enable_git`**                  | `true`  | Show info about Git repository.                      |
+| **`pure_symbol_git_dirty`**            | `*`     | Repository is Dirty (uncommitted/untracked changes). |
+| **`pure_symbol_git_stash`**            | `≡`     | Repository git stash status.                         |
+| **`pure_symbol_git_unpulled_commits`** | `⇣`     | Branch is behind upstream (commits to pull).         |
+| **`pure_symbol_git_unpushed_commits`** | `⇡`     | Branch is ahead upstream (commits to push).          |
+
+> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)?
+
+### Kubernetes
+
+| Option                       | Default | Description                                       |
+| :--------------------------- | :------ | :------------------------------------------------ |
+| **`pure_symbol_k8s_prefix`** | `☸`     | Prefix when being connected to Kubernetes/K8s     |
+| **`pure_enable_k8s`**        | `false` | `true`: shows `kubernetes` context and namespace. |
+
+### VI Mode
+
+| Option                                     | Default | Description                                                                                     |
+| :----------------------------------------- | :------ | :---------------------------------------------------------------------------------------------- |
+| **`pure_reverse_prompt_symbol_in_vimode`** | `true`  | `true`: `❮` indicate a non-insert mode.<br/>`false`: indicate vi mode with `[I]`, `[N]`, `[V]`. |
+| **`pure_symbol_reverse_prompt`**           | `❮`     | VI non-insert mode symbol.                                                                      |
+
+### Container Detection (Docker)
+
+| Option                                | Default | Description                                                                                                                                                                    |
+| :------------------------------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`pure_enable_container_detection`** | `true`  | `false`: Do not check _pure_ runs inside a container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).<br/>:warning: Detection is a bit [tricky across OSes][container-detection]. |
+| **`pure_symbol_container_prefix`**    |         | Prefix when being inside a container ([to customize][to-set])                                                                                                                  |
+
+### Working as Root
+
+| Option                               | Default | Description                                           |
+| :----------------------------------- | :------ | :---------------------------------------------------- |
+| **`pure_show_prefix_root_prompt`**   | `false` | `true`: shows prompt prefix when logged in as `root`. |
+| **`pure_symbol_prefix_root_prompt`** | `#`     | Prefix prompt when logged in as `root`.               |
+
+### SSH Session
+
+| Option                       | Default | Description                                                               |
+| :--------------------------- | :------ | :------------------------------------------------------------------------ |
+| **`pure_symbol_ssh_prefix`** |         | Prefix when being connected to SSH session (default: [undefined][to-set]) |
+
+### Python Virtualenv
+
+| Option                              | Default | Description                                                                  |
+| :---------------------------------- | :------ | :--------------------------------------------------------------------------- |
+| **`pure_enable_virtualenv`**        | `true`  | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`).       |
+| **`pure_symbol_virtualenv_prefix`** |         | Prefix when a Python virtual env is activated (default: [undefined][to-set]) |
+
+### Time & Duration
+
+| Option                                     | Default | Description                                                         |
+| :----------------------------------------- | :------ | :------------------------------------------------------------------ |
+| **`pure_show_system_time`**                | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`). |
+| **`pure_show_subsecond_command_duration`** | `false` | Show subsecond (ex. 1.5s) in command duration.                      |
+| **`pure_threshold_command_duration`**      | `5`     | Show command duration when above this value (seconds).              |
+
+### Title
+
+| Option                                                   | Default | Description                                                                               |
+| :------------------------------------------------------- | :------ | :---------------------------------------------------------------------------------------- |
+| **`pure_symbol_title_bar_separator`**                    | `-`     | Separator in terminal's windows title.                                                    |
+| **`pure_shorten_window_title_current_directory_length`** | `0`     | Shorten every window title path component but the last to X characters (0 do not shorten) |
+
+### Current Working Directory
+
+| Option                                             | Default | Description                                                                         |
+| :------------------------------------------------- | :------ | :---------------------------------------------------------------------------------- |
+| **`pure_begin_prompt_with_current_directory`**     | `true`  | `true`: _`pwd` `git`, `SSH`, duration_.<br/>`false`: _`SSH` `pwd` `git`, duration_. |
+| **`pure_shorten_prompt_current_directory_length`** | `0`     | Shorten every prompt path component but the last to X characters (0 do not shorten) |
+
+### Check For New Release
+
+| Option                           | Default | Description                                               |
+| :------------------------------- | :------ | :-------------------------------------------------------- |
+| **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) |
+
+### Single Line Prompt
+
+| Option                               | Default | Description                             |
+| :----------------------------------- | :------ | :-------------------------------------- |
+| **`pure_enable_single_line_prompt`** | `false` | `true`: Compact prompt as a single line |
+
+### Separate Error Symbol
+
+| Option                              | Default | Description                                                         |
+| :---------------------------------- | :------ | :------------------------------------------------------------------ |
+| **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a second prompt symbol][exit-code]. |
+
+### Jobs
+
+| Option               | Default | Description                 |
+| :------------------- | :------ | :-------------------------- |
+| **`pure_show_jobs`** | `false` | Show Number of running jobs |

docs/components/features-overview.md

@@ -0,0 +1,30 @@
+### Overview
+
+Fully **customizable** (colors, symbols and features):
+
+* Excellent prompt character `❯` :
+  * Change `❯` to red when previous command has failed ;
+  * Start prompt with _current working directory_ 🏴 ;
+  * Compact-mode (single-line prompt) 🏴 ;
+* Display _current folder_  tail ;
+* check for new release on start 🏴 ;
+* Display _username_ and _hostname_ when in an `SSH` session ;
+* Display command _duration_ when longer than `5` seconds ;
+* Display `Python` _virtualenv_ when activated 🏴 ;
+* Display `VI` mode and custom symbol for non-insert mode 🏴 ;
+* Display `kubernetes` context and namespace 🏴 ;
+* Display container indicator (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴
+* Show system time 🏴 ;
+* Show number of running jobs 🏴 ;
+* Prefix when `root` 🏴 ;
+* Display `git` branch name 🏴 ;
+  * Display `*` when `git` repository is _dirty_ ;
+  * Display `≡` when `git` repository is _stashed_ ;
+  * Display `⇡` when branch is _ahead_ (commits to push) ;
+  * Display `⇣` when branch is _behind_ (commits to pull) ;
+  * Async update when [configured with fish-async-prompt](https://github.com/pure-fish/pure/wiki/Async-git-Prompt) ;
+* Update terminal title with _current folder_ and _command_ ;
+* Detect when running in a container ;
+* Shorten _current folder_ component 🏴;
+
+🏴: Enabled or disabled via a [feature flag](#-features-flags).

docs/components/installation.md

@@ -0,0 +1,21 @@
+!!! success
+
+    Pure requires Fish **`≥3.x`**
+
+=== "[Fisher](https://github.com/jorgebucaran/fisher)"
+
+    ```shell
+    fisher install pure-fish/pure
+    ```
+
+=== "Manually"
+
+    1. Download the installer to `/tmp`
+        ```shell
+        curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent
+        ```
+
+    2. Source and trigger the installer
+        ```
+        source /tmp/pure_installer.fish; and install_pure
+        ```

docs/contributing.md

@@ -0,0 +1,5 @@
+# Contribution Guide
+
+{% include '../CODE_OF_CONDUCT.md' %}
+{% include '../CONTRIBUTING.md' %}
+{% include './RELEASE.md' %}