docs/revamp documentation and automate screenshots

.github/workflows/ci.yml

@@ -75,3 +75,7 @@ jobs:
     if: contains(github.ref, 'master')
     uses: ./.github/workflows/bump-version.yml
     secrets: inherit
+
+  publish-doc:
+    uses: ./.github/workflows/doc.yml
+    secrets: inherit

.github/workflows/doc.yml

@@ -0,0 +1,31 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/
+
+  pull_request:
+    # types:
+    #   - opened
+    #   - reopened
+    #   - synchronize
+    #   - ready_for_review
+    paths:
+      - docs/
+  workflow_call:
+
+jobs:
+  build:
+    name: Deploy docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: docs/requirements.txt

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: Work inside a Docker
 
-## 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

README.md

@@ -6,9 +6,7 @@
 
 </div>
 
-> ##### :arrow_up: Hey! Want to migrate from v3.x to v4.x? Check our [**migration guide**](https://github.com/pure-fish/pure/releases/tag/v4.0.0), done with ❤️
-
-# pure
+# pure  `❯❮❯`
 
 > Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure).
 
@@ -17,25 +15,16 @@
   <a href="https://camo.githubusercontent.com/5934e8c1d3b5f9218d05d5e1741e23963a7803d6098236d36e586336a6c6a5b7/68747470733a2f2f692e696d6775722e636f6d2f714a646f6e716f2e706e67" target=blank><img width=440 src=https://camo.githubusercontent.com/5934e8c1d3b5f9218d05d5e1741e23963a7803d6098236d36e586336a6c6a5b7/68747470733a2f2f692e696d6775722e636f6d2f714a646f6e716f2e706e67 alt="Pure with light colorscheme"></a>
 </div>
 
-## :rocket: Install
-
-**:warning: requirements**: fish `≥3.x`
+## Documentation
 
-### [Fisher](https://github.com/jorgebucaran/fisher)
+:sparkles: Check-out our [brand-new documentation][doc] for configurations, features and colours as well as contributing guide.
 
-```shell
-fisher install pure-fish/pure
-```
-
-### Manually
+## :rocket: Install
 
-Via [cURL](https://curl.haxx.se):
+**:warning: requirements**: fish `≥3.x`, [fisher](https://github.com/jorgebucaran/fisher):
 
 ```shell
-# Download the installer to `/tmp`
-curl git.io/pure-fish --output /tmp/pure_installer.fish --location --silent
-# Source and trigger the installer
-source /tmp/pure_installer.fish; and install_pure
+fisher install pure-fish/pure
 ```
 
 ## Features
@@ -69,117 +58,44 @@ Fully **customizable** (colors, symbols and features):
 - Shorten _current folder_ component in prompt and window title 🏴;
 - Truncate _current folder_ component in prompt and window title 🏴;
 
-🏴: Enabled or disabled via a [feature flag](#-features-flags).
+🏴: Enabled or disabled via a [feature flag][features].
 
-## :paintbrush: Configuration
+## Configuration
 
-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._:
+See [How to configure pure prompt?][configure]
 
-```shell
-set --universal pure_show_system_time true
-set --universal pure_color_system_time pure_color_mute
-```
+## Features' Flags
+
+See [Features and their respective options][features].
+
+## :heart: Contribute
 
-### Prompt Symbol
-
-| Option                                 | Default | Description                                                                  |
-| :------------------------------------- | :------ | :--------------------------------------------------------------------------- |
-| **`pure_symbol_container_prefix`**     |         | Prefix when being inside a container ([to customize][to-set])                |
-| **`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).                                  |
-| **`pure_symbol_k8s_prefix`**           | `☸`     | Prefix when being connected to Kubernetes/K8s                                |
-| **`pure_symbol_prefix_root_prompt`**   | `#`     | Prefix prompt when logged in as `root`.                                      |
-| **`pure_symbol_prompt`**               | `❯`     | Prompt symbol.                                                               |
-| **`pure_symbol_reverse_prompt`**       | `❮`     | VI non-insert mode symbol.                                                   |
-| **`pure_symbol_ssh_prefix`**           |         | Prefix when being connected to SSH session (default: [undefined][to-set])    |
-| **`pure_symbol_title_bar_separator`**  | `-`     | Separator in terminal's windows title.                                       |
-| **`pure_symbol_nixdevshell_prefix`**   | `❄️`     | Prefix when a `nix develop` shell is activated (default: [undefined][to-set]) |
-| **`pure_symbol_virtualenv_prefix`**    |         | Prefix when a Python virtual env is activated (default: [undefined][to-set]) |
-
-> :information_source: Need [safer `git` symbols](https://github.com/sindresorhus/pure/wiki/Customizations,-hacks-and-tweaks#safer-symbols)?
-
-### 🔌 Features' Flags
-
-| Option                                                   | Default | Description                                                                                                                                                         |
-| :------------------------------------------------------- | :------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`pure_begin_prompt_with_current_directory`**           | `true`  | `true`: _`pwd` `git`, `SSH`, duration_.<br/>`false`: _`SSH` `pwd` `git`, duration_.                                                                                 |
-| **`pure_check_for_new_release`**                         | `false` | `true`: check repo for new release (on every shell start)                                                                                                           |
-| **`pure_enable_container_detection`**                    | `true`  | `false`: Do not check if run in container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).<br/>:warning: Detection is a bit [tricky across OSes][container-detection]. |
-| **`pure_enable_git`**                                    | `true`  | Show info about Git repository.                                                                                                                                     |
-| **`pure_enable_k8s`**                                    | `false` | `true`: shows `kubernetes` context and namespace.                                                                                                                   |
-| **`pure_enable_single_line_prompt`**                     | `false` | `true`: Compact prompt as a single line                                                                                                                             |
-| **`pure_enable_nixdevshell`**                            | `false` | Indicate if a `nix develop` shell is activated (based on `IN_NIX_SHELL`).                                                                                           |
-| **`pure_enable_virtualenv`**                             | `true`  | Show virtual env name (based on `VIRTUAL_ENV` or `CONDA_DEFAULT_ENV`).                                                                                              |
-| **`pure_reverse_prompt_symbol_in_vimode`**               | `true`  | `true`: `❮` indicate a non-insert mode.<br/>`false`: indicate vi mode with `[I]`, `[N]`, `[V]`.                                                                     |
-| **`pure_separate_prompt_on_error`**                      | `false` | Show last command [exit code as a separate character][exit-code].                                                                                                   |
-| **`pure_shorten_prompt_current_directory_length`**       | `0`     | Shorten every prompt path component but the last to X characters (0 do not shorten)                                                                                 |
-| **`pure_shorten_window_title_current_directory_length`** | `0`     | Shorten every window title path component but the last to X characters (0 do not shorten)                                                                           |
-| **`pure_show_jobs`**                                     | `false` | Show Number of running jobs                                                                                                                                         |
-| **`pure_show_prefix_root_prompt`**                       | `false` | `true`: shows prompt prefix when logged in as `root`.                                                                                                               |
-| **`pure_show_subsecond_command_duration`**               | `false` | Show subsecond (ex. 1.5s) in command duration.                                                                                                                      |
-| **`pure_show_system_time`**                              | `false` | `true`: shows system time before the prompt symbol (as `%H:%M:%S`).                                                                                                 |
-| **`pure_threshold_command_duration`**                    | `5`     | Show command duration when above this value (seconds).                                                                                                              |
-| **`pure_truncate_prompt_current_directory_keeps`**       | `0`    | Truncate working directory path in prompt, but keeps the last to `n` components (`0` full path in current directory)                                               |
-| **`pure_truncate_window_title_current_directory_keeps`** | `0`    | Truncate working directory path in window title, but keeps the last to `n` components (`0` full path in window title)                                         |
-
-### 🎨 Colours
-
-> :information_source: See [`set_color`][fish-set-color] documentation for full possibilities.
-
-> :warning: 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`  |
-
-## :+1: Contribute
-
-**requirements:** [`docker`](https://docs.docker.com/install/) (isolate from your environment), get familiar with [CONTRIBUTING.md][contributing] guidelines.
-
-Specify the [`FISH_VERSION`][fish-releases] you want, and the `CMD` executed by the container:
-
-    make build-pure-on FISH_VERSION=3.3.1
-    make dev-pure-on FISH_VERSION=3.3.1 CMD="fishtape tests/*.test.fish"
-
-## :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)
+If you have any ideas or suggestions, we encourage you to submit a pull request. Our team will review and discuss your contribution.
+
+Checkout our [Contribution Guide][contribution] to get familiar with our conventions and requirements.
+
+## :man_technologist: People
+
+- [Édouard Lopez](https://github.com/edouard-lopez) product lead ;
+- [@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/rafaelrinaldi) for starting the project and publishing the initial releases
 
-## :classical_building: License
+## [MIT][MIT]  License
 
-[MIT][MIT]
+[doc]: https://pure-fish.github.io/pure/
+[configure]: https://pure-fish.github.io/pure/#configuration
+[features]: https://pure-fish.github.io/pure/#overview
+[contribution]:https://pure-fish.github.io/pure/contributing/
 
-[to-set]: #paintbrush-configuration
 [ci-link]: <https://github.com/pure-fish/pure/actions> "Github CI"
 [ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square
 
 [fish-3]: <https://img.shields.io/badge/fish-v3-007EC7.svg?style=flat-square> "Support Fish 3"
-[exit-code]: <https://github.com/sindresorhus/pure/wiki#show-exit-code-of-last-command-as-a-separate-prompt-character> "See pure-zsh wiki"
-[fish-releases]: https://github.com/fish-shell/fish-shell/releases
 [docker-images]: https://github.com/andreiborisov/docker-fish/
 [MIT]: LICENSE.md
-[fish-set-color]: https://fishshell.com/docs/current/cmds/set_color.html
-[container-detection]: https://stackoverflow.com/q/23513045/802365
 
 [release-version]: https://img.shields.io/github/v/tag/pure-fish/pure?label=latest%20&style=flat-square
 [release-link]: https://github.com/pure-fish/pure/releases "GitHub tag (latest SemVer)"
 [sponsors]: https://img.shields.io/github/sponsors/edouard-lopez?label=💰&style=flat-square "GitHub Sponsors"
 [sponsor-link]: https://github.com/sponsors/edouard-lopez/ "Become a sponsor"
-
-[contributing]: CONTRIBUTING.md

docker/Dockerfile

@@ -38,5 +38,27 @@ RUN echo 'Symlink dev files' \
     && ln -nfs "$(pwd)"/conf.d/*.fish ../conf.d/ \
     && ln -nfs "$(pwd)"/functions/*.fish ../functions/
 
+FROM with-pure-installed as with-terminal-screenshot-installed
+USER root
+RUN apk add \
+    --no-cache \
+    chromium \
+    nss \
+    freetype \
+    harfbuzz \
+    ca-certificates \
+    ttf-freefont \
+    nodejs \
+    npm
+
+# Tell Puppeteer to skip installing Chrome. We'll be using the installed package.
+ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium-browser
+
+RUN npm install \
+    --global \
+    terminal-screenshot \
+    puppeteer
+USER nemo
+
 ENTRYPOINT ["fish", "-c"]
 CMD ["fishtape tests/*.test.fish"]

docker/doc.Dockerfile

@@ -0,0 +1,9 @@
+FROM squidfunk/mkdocs-material:9
+
+COPY ./docs/requirements.txt /docs/
+RUN pip install \
+    --no-cache-dir \
+    --requirement ./requirements.txt
+
+ENTRYPOINT ["mkdocs"]
+CMD ["serve", "--dev-addr=0.0.0.0:8000"]

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/