docs: revamp feature list and link readme to doc

* fix markdown errors
pure-fish · Jan 27, 2024 · 71b541c · 71b541c
1 parent 536ce3a
commit 71b541c
Show file tree

Hide file tree

Showing 13 changed files with 149 additions and 72 deletions.
diff --git 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
@@ -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
@@ -1,12 +1,13 @@
+<!-- markdownlint-disable MD041 -->
 <div align="center">
 
-<img src="https://user-images.githubusercontent.com/1212392/262604075-db5d0ad2-a7ed-4a62-a1cc-ec677cf76351.png" width="61.8%"/><br>
+<img src="https://user-images.githubusercontent.com/1212392/262604075-db5d0ad2-a7ed-4a62-a1cc-ec677cf76351.png" width="61.8%" alt="Pure.fish logo"/><br>
 
 [![ci-status]][ci-link] ![fish-3] [![release-version]][release-link] [![sponsors]][sponsor-link] <!-- 0 width spaces on this line -->
 
 </div>
 
-# 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
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 ## Releasing
 
 Release process is automated in the pipeline with the following steps.

diff --git a/docs/components/colours.md b/docs/components/colours.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 !!! tip
 
     See [`set_color`][fish-set-color] documentation for full possibilities.

diff --git a/docs/components/configuration.md b/docs/components/configuration.md
@@ -1,4 +1,4 @@
-
+<!-- markdownlint-disable MD041 -->
 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
@@ -1,17 +1,28 @@
-
+<!-- markdownlint-disable MD041 -->
 ### 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                                                                                                                                                                    |
 | :------------------------------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **`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])                                                                                                                  |
 
+[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]: <https://github.com/sindresorhus/pure/wiki#show-exit-code-of-last-command-as-a-separate-prompt-character> "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
@@ -1,30 +1,55 @@
+<!-- markdownlint-disable MD041 -->
 ### 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
+<!-- markdownlint-disable MD051 -->
+[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
+<!-- markdownlint-enable MD051 -->
diff --git a/docs/components/hero-banner.md b/docs/components/hero-banner.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable-next-line MD041 -->
 > Pretty, minimal and fast Fish 🐟 prompt, ported from [`zsh`](https://github.com/sindresorhus/pure).
 
 <div align=center>

diff --git a/docs/components/installation.md b/docs/components/installation.md
@@ -1,3 +1,4 @@
+<!-- markdownlint-disable MD041 -->
 !!! success
 
     Pure requires Fish **`≥3.x`**

diff --git a/docs/components/logo.md b/docs/components/logo.md
@@ -0,0 +1,6 @@
+<!-- markdownlint-disable MD041 -->
+<div align="center">
+
+<img src="https://user-images.githubusercontent.com/1212392/262604075-db5d0ad2-a7ed-4a62-a1cc-ec677cf76351.png" width="61.8%" alt="Pure.fish logo"/><br>
+
+</div>
diff --git a/docs/index.md b/docs/index.md
@@ -1,10 +1,7 @@
-<div align="center">
+<!-- markdownlint-disable MD041 -->
+{% include 'components/logo.md' %}
 
-<img src="https://user-images.githubusercontent.com/1212392/262604075-db5d0ad2-a7ed-4a62-a1cc-ec677cf76351.png" width="61.8%"/><br>
-
-</div>
-
-# pure
+# _Pure_  `❯❮❯`
 
 {% include 'components/hero-banner.md' %}
 
@@ -26,14 +23,11 @@
 {% include 'components/colours.md' %}
 
 <!-- markdownlint-disable MD053 -->
-[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
-[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
@@ -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/