From 71b541c22e09a09d15dc9085a4819c5cc2db2593 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89douard=20Lopez?= Date: Sat, 27 Jan 2024 10:59:12 +0100 Subject: [PATCH] docs: revamp feature list and link readme to doc * fix markdown errors --- .github/workflows/doc.yml | 2 +- .markdownlint.yml | 11 ++++ README.md | 89 +++++++++++++++++----------- docs/RELEASE.md | 1 + docs/components/colours.md | 1 + docs/components/configuration.md | 2 +- docs/components/features-list.md | 17 +++++- docs/components/features-overview.md | 75 +++++++++++++++-------- docs/components/hero-banner.md | 1 + docs/components/installation.md | 1 + docs/components/logo.md | 6 ++ docs/index.md | 12 +--- mkdocs.yml | 3 +- 13 files changed, 149 insertions(+), 72 deletions(-) create mode 100644 .markdownlint.yml create mode 100644 docs/components/logo.md diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index f49e64fb..1e17f5f8 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -4,7 +4,7 @@ on: branches: - master paths: - - docs/ + - docs/**/* pull_request: # types: diff --git a/.markdownlint.yml b/.markdownlint.yml new file mode 100644 index 00000000..e82d377f --- /dev/null +++ b/.markdownlint.yml @@ -0,0 +1,11 @@ +--- +default: true +extends: null +MD007: false +MD013: false +MD033: + allowed_elements: + - br + - img + - div + - a diff --git a/README.md b/README.md index b8364c85..82428489 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,13 @@ +
-
+Pure.fish logo
[![ci-status]][ci-link] ![fish-3] [![release-version]][release-link] [![sponsors]][sponsor-link]
-# pure `❯❮❯` +# _Pure_ `❯❮❯` > Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure). @@ -31,34 +32,36 @@ fisher install pure-fish/pure 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 `nix develop` shell indicator when activated 🏴 ; -- 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 in prompt and window title 🏴; -- Truncate _current folder_ component in prompt and window title 🏴; - -🏴: Enabled or disabled via a [feature flag][features]. +* [Excellent prompt character `❯` 🛠][prompt-symbol]: + + * [Change `❯` to red when previous command has failed 🛠][separate-error-symbol] ; + * [Start prompt with _current working directory_ 🏴][current-working-directory] ; + * [Compact-mode (single-line prompt) 🏴][single-line-prompt] ; + +* [Check for new release on start 🏴🐌][check-for-new-release] ; +* [Display _username_ and _hostname_ when in an `SSH` session 🛠][ssh-session] ; +* [Display command _duration_ when longer than `5` seconds 🛠][time-duration] ; +* [Display `Python` _virtualenv_ when activated 🏴🛠][python-virtualenv] ; +* [Display `VI` mode and custom symbol for non-insert mode 🏴🛠][vi-mode] ; +* [Display `kubernetes` context and namespace 🏴🛠][kubernetes] ; +* [Detect when running in a container (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴🛠][container-detection-docker] +* [Indicate if a `nix develop` shell is activated 🏴🛠][nix-os]. +* [Show system time 🏴][time-duration] ; +* [Show number of running jobs 🏴][jobs] ; +* [Prefix when `root` 🏴🛠][working-as-root] ; +* [Display `git` branch name 🏴🛠][git] ; + + * 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][async] ; + +* [Update terminal title with _current folder_ and _command_ 🛠][title] ; +* [Shorten or truncate _current folder_ component 🏴🛠][current-working-directory] ; +* and more… + +🏴 means it's controlled by a feature flag, 🛠 mean it's configurable. ## Configuration @@ -76,10 +79,10 @@ Checkout our [Contribution Guide][contribution] to get familiar with our convent ## :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 +* [É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 ## [MIT][MIT] License @@ -99,3 +102,21 @@ Checkout our [Contribution Guide][contribution] to get familiar with our convent [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" + +[async]: https://github.com/pure-fish/pure/wiki/Async-git-Prompt +[check-for-new-release]: https://pure-fish.github.io/pure/#check-for-new-release +[container-detection-docker]: https://pure-fish.github.io/pure/#container-detection-docker +[current-working-directory]: https://pure-fish.github.io/pure/#current-working-directory +[git]: https://pure-fish.github.io/pure/#git +[jobs]: https://pure-fish.github.io/pure/#jobs +[kubernetes]: https://pure-fish.github.io/pure/#kubernetes +[nix-os]: https://pure-fish.github.io/pure/#nix-os +[prompt-symbol]: https://pure-fish.github.io/pure/#prompt-symbol +[python-virtualenv]: https://pure-fish.github.io/pure/#python-virtualenv +[separate-error-symbol]: https://pure-fish.github.io/pure/#separate-error-symbol +[single-line-prompt]: https://pure-fish.github.io/pure/#single-line-prompt +[ssh-session]: https://pure-fish.github.io/pure/#ssh-session +[time-duration]: https://pure-fish.github.io/pure/#time-duration +[title]: https://pure-fish.github.io/pure/#title +[vi-mode]: https://pure-fish.github.io/pure/#vi-mode +[working-as-root]: https://pure-fish.github.io/pure/#working-as-root diff --git a/docs/RELEASE.md b/docs/RELEASE.md index 6e16db50..86cbf1b5 100644 --- a/docs/RELEASE.md +++ b/docs/RELEASE.md @@ -1,3 +1,4 @@ + ## Releasing Release process is automated in the pipeline with the following steps. diff --git a/docs/components/colours.md b/docs/components/colours.md index 54cda90e..519c8d44 100644 --- a/docs/components/colours.md +++ b/docs/components/colours.md @@ -1,3 +1,4 @@ + !!! tip See [`set_color`][fish-set-color] documentation for full possibilities. diff --git a/docs/components/configuration.md b/docs/components/configuration.md index dc2c03cd..968c90fc 100644 --- a/docs/components/configuration.md +++ b/docs/components/configuration.md @@ -1,4 +1,4 @@ - + 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 diff --git a/docs/components/features-list.md b/docs/components/features-list.md index 7bcbbd5d..60a893bc 100644 --- a/docs/components/features-list.md +++ b/docs/components/features-list.md @@ -1,10 +1,19 @@ - + ### Check For New Release | Option | Default | Description | | :------------------------------- | :------ | :-------------------------------------------------------- | | **`pure_check_for_new_release`** | `false` | `true`: check repo for new release (on every shell start) | +!!! success "🐌 Faster Prompt" + + Checking new release send a HTTP request that slow down your prompt rendering + as it wait for remote server response. Set it to `false` speed up rendering: + + ```fish + set --universal pure_check_for_new_release false + ``` + ### Container Detection (Docker) | Option | Default | Description | @@ -12,6 +21,8 @@ | **`pure_enable_container_detection`** | `true` | `false`: Do not check _pure_ runs inside a container (e.g. `docker`, `podman`, `LXC`/`LXD`, etc.).
:warning: Detection is a bit [tricky across OSes][container-detection]. | | **`pure_symbol_container_prefix`** | | Prefix when being inside a container ([to customize][to-set]) | +[container-detection]: https://stackoverflow.com/q/23513045/802365 + ### Current Working Directory | Option | Default | Description | @@ -77,6 +88,8 @@ | :---------------------------------- | :------ | :------------------------------------------------------------------ | | **`pure_separate_prompt_on_error`** | `false` | Show last command [exit code as a second prompt symbol][exit-code]. | +[exit-code]: "See pure-zsh wiki" + ### Single Line Prompt | Option | Default | Description | @@ -118,3 +131,5 @@ | :----------------------------------- | :------ | :---------------------------------------------------- | | **`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`. | + +[to-set]: https://pure-fish.github.io/pure/#configuration diff --git a/docs/components/features-overview.md b/docs/components/features-overview.md index f50781ca..30912a4f 100644 --- a/docs/components/features-overview.md +++ b/docs/components/features-overview.md @@ -1,30 +1,55 @@ + ### 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 🏴; +* [Excellent prompt character `❯` 🛠][prompt-symbol]: -🏴: Enabled or disabled via a [feature flag](#-features-flags). + * [Change `❯` to red when previous command has failed 🛠][separate-error-symbol] ; + * [Start prompt with _current working directory_ 🏴][current-working-directory] ; + * [Compact-mode (single-line prompt) 🏴][single-line-prompt] ; + +* [Check for new release on start 🏴🐌][check-for-new-release] ; +* [Display _username_ and _hostname_ when in an `SSH` session 🛠][ssh-session] ; +* [Display command _duration_ when longer than `5` seconds 🛠][time-duration] ; +* [Display `Python` _virtualenv_ when activated 🏴🛠][python-virtualenv] ; +* [Display `VI` mode and custom symbol for non-insert mode 🏴🛠][vi-mode] ; +* [Display `kubernetes` context and namespace 🏴🛠][kubernetes] ; +* [Detect when running in a container (e.g. `docker`, `podman`, `LXC`/`LXD`) 🏴🛠][container-detection-docker] +* [Indicate if a `nix develop` shell is activated 🏴🛠][nix-os]. +* [Show system time 🏴][time-duration] ; +* [Show number of running jobs 🏴][jobs] ; +* [Prefix when `root` 🏴🛠][working-as-root] ; +* [Display `git` branch name 🏴🛠][git] ; + + * 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][async] ; + +* [Update terminal title with _current folder_ and _command_ 🛠][title] ; +* [Shorten or truncate _current folder_ component 🏴🛠][current-working-directory] ; +* and more… + +🏴 means it's controlled by a feature flag, 🛠 mean it's configurable. + +[async]: https://github.com/pure-fish/pure/wiki/Async-git-Prompt + +[check-for-new-release]: #check-for-new-release +[container-detection-docker]: #container-detection-docker +[current-working-directory]: #current-working-directory +[git]: #git +[jobs]: #jobs +[kubernetes]: #kubernetes +[nix-os]: #nix-os +[prompt-symbol]: #prompt-symbol +[python-virtualenv]: #python-virtualenv +[separate-error-symbol]: #separate-error-symbol +[single-line-prompt]: #single-line-prompt +[ssh-session]: #ssh-session +[time-duration]: #time-duration +[title]: #title +[vi-mode]: #vi-mode +[working-as-root]: #working-as-root + diff --git a/docs/components/hero-banner.md b/docs/components/hero-banner.md index dffe659f..7f615196 100644 --- a/docs/components/hero-banner.md +++ b/docs/components/hero-banner.md @@ -1,3 +1,4 @@ + > Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure).
diff --git a/docs/components/installation.md b/docs/components/installation.md index 591c0dd6..46bd1403 100644 --- a/docs/components/installation.md +++ b/docs/components/installation.md @@ -1,3 +1,4 @@ + !!! success Pure requires Fish **`≥3.x`** diff --git a/docs/components/logo.md b/docs/components/logo.md new file mode 100644 index 00000000..00f0376f --- /dev/null +++ b/docs/components/logo.md @@ -0,0 +1,6 @@ + +
+ +Pure.fish logo
+ +
diff --git a/docs/index.md b/docs/index.md index c8a8274d..7961b809 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,10 +1,7 @@ -
+ +{% include 'components/logo.md' %} -
- -
- -# pure +# _Pure_ `❯❮❯` {% include 'components/hero-banner.md' %} @@ -26,14 +23,11 @@ {% include 'components/colours.md' %} -[to-set]: #paintbrush-configuration [ci-link]: "Github CI" [ci-status]: https://img.shields.io/github/actions/workflow/status/pure-fish/pure/.github/workflows/ci.yml?style=flat-square [fish-3]: "Support Fish 3" -[exit-code]: "See pure-zsh wiki" [fish-releases]: https://github.com/fish-shell/fish-shell/releases -[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)" diff --git a/mkdocs.yml b/mkdocs.yml index a2c513b7..4495cce8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,5 @@ -site_name: Pure.fish +--- +site_name: "Pure.fish Documentation" site_description: " Pretty, minimal and fast Fish 🐟 prompt" site_author: "Édouard Lopez" docs_dir: docs/