docs: improve several plugin READMEs and add one for `ssh` plugin

23 files changed, 123 insertions, 90 deletions

diff --git a/plugins/aliases/README.md b/plugins/aliases/README.md
index 14f9c5c53..5a7e7dfc6 100644
--- a/plugins/aliases/README.md
+++ b/plugins/aliases/README.md
@@ -1,7 +1,5 @@
 # Aliases cheatsheet
 
-**Maintainer:** [@hqingyi](https://github.com/hqingyi)
-
 With lots of 3rd-party amazing aliases installed, this plugin helps list the shortcuts
 that are currently available based on the plugins you have enabled.
 
@@ -13,6 +11,8 @@ plugins=(aliases)
 
 Requirements: Python needs to be installed.
 
+**Maintainer:** [@hqingyi](https://github.com/hqingyi)
+
 ## Usage
 
 - `als`: show all aliases by group
diff --git a/plugins/ansible/README.md b/plugins/ansible/README.md
index dd0e1ce03..6a06962ee 100644
--- a/plugins/ansible/README.md
+++ b/plugins/ansible/README.md
@@ -1,7 +1,5 @@
 # ansible plugin
 
-## Introduction
-
 The `ansible plugin` adds several aliases for useful [ansible](https://docs.ansible.com/ansible/latest/index.html) commands and [aliases](#aliases).
 
 To use it, add `ansible` to the plugins array of your zshrc file:
diff --git a/plugins/arduino-cli/README.md b/plugins/arduino-cli/README.md
index 91bda9067..821d72bbf 100644
--- a/plugins/arduino-cli/README.md
+++ b/plugins/arduino-cli/README.md
@@ -1,6 +1,7 @@
 # Arduino CLI plugin
 
 This plugin adds completion for the [arduino-cli](https://github.com/arduino/arduino-cli) tool.
+
 To use it, add `arduino-cli` to the plugins array in your zshrc file:
 
 ```zsh
diff --git a/plugins/asdf/README.md b/plugins/asdf/README.md
index f047860e2..4af69a75c 100644
--- a/plugins/asdf/README.md
+++ b/plugins/asdf/README.md
@@ -1,7 +1,5 @@
 ## asdf
 
-**Maintainer:** [@RobLoach](https://github.com/RobLoach)
-
 Adds integration with [asdf](https://github.com/asdf-vm/asdf), the extendable version manager, with support for Ruby, Node.js, Elixir, Erlang and more.
 
 ### Installation
@@ -28,3 +26,7 @@ asdf install nodejs latest
 asdf global nodejs latest
 asdf local nodejs latest
 ```
+
+### Maintainer
+
+- [@RobLoach](https://github.com/RobLoach)
diff --git a/plugins/chucknorris/README.md b/plugins/chucknorris/README.md
index b51875de9..0562b3b59 100644
--- a/plugins/chucknorris/README.md
+++ b/plugins/chucknorris/README.md
@@ -1,6 +1,6 @@
 # chucknorris
 
-Chuck Norris fortunes plugin for Oh My Zsh. Perfectly suitable as MOTD.
+Fortunes plugin for Chuck Norris for Oh My Zsh. Perfectly suitable as MOTD.
 
 To use it add `chucknorris` to the plugins array in you zshrc file.
 
diff --git a/plugins/dbt/README.md b/plugins/dbt/README.md
index e05d79cc3..74ae631cd 100644
--- a/plugins/dbt/README.md
+++ b/plugins/dbt/README.md
@@ -1,13 +1,11 @@
 # dbt plugin
 
-## Introduction
-
 The `dbt plugin` adds several aliases for useful [dbt](https://docs.getdbt.com/) commands and
 [aliases](#aliases).
 
 To use it, add `dbt` to the plugins array of your zshrc file:
 
-```
+```zsh
 plugins=(... dbt)
 ```
 
@@ -26,4 +24,4 @@ plugins=(... dbt)
 
 ## Maintainer
 
-### [msempere](https://github.com/msempere)
+- [msempere](https://github.com/msempere)
diff --git a/plugins/fancy-ctrl-z/README.md b/plugins/fancy-ctrl-z/README.md
index 82a4fd75e..7766c51eb 100644
--- a/plugins/fancy-ctrl-z/README.md
+++ b/plugins/fancy-ctrl-z/README.md
@@ -1,4 +1,14 @@
-# Use Ctrl-Z to switch back to Vim
+# fancy-ctrl-z
+
+Allows pressing Ctrl-Z again to switch back to a background job.
+
+To use it, add `fancy-ctrl-z` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... fancy-ctrl-z)
+```
+
+## Motivation
 
 I frequently need to execute random commands in my shell. To achieve it I pause
 Vim by pressing Ctrl-z, type command and press fg<Enter> to switch back to Vim.
diff --git a/plugins/gatsby/README.md b/plugins/gatsby/README.md
index 36846a228..cc1bd392e 100644
--- a/plugins/gatsby/README.md
+++ b/plugins/gatsby/README.md
@@ -1,6 +1,6 @@
 # gatsby autocomplete plugin
 
-* Adds autocomplete options for all gatsby commands.
+Adds autocomplete options for all gatsby commands.
 
 ## Requirements
 
diff --git a/plugins/isodate/README.md b/plugins/isodate/README.md
index 1ec75b2d4..5329310c2 100644
--- a/plugins/isodate/README.md
+++ b/plugins/isodate/README.md
@@ -1,7 +1,5 @@
 # Isodate plugin
 
-**Maintainer:** [@Frani](https://github.com/frani)
-
 This plugin adds completion for the [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601),
 as well as some aliases for common Date commands.
 
@@ -11,6 +9,8 @@ To use it, add `isodate` to the plugins array in your zshrc file:
 plugins=(... isodate)
 ```
 
+**Maintainer:** [@Frani](https://github.com/frani)
+
 ## Aliases
 
 | Alias         | Command                              | Description                                                                |
diff --git a/plugins/jira/README.md b/plugins/jira/README.md
index 1c6930298..7cfb81b19 100644
--- a/plugins/jira/README.md
+++ b/plugins/jira/README.md
@@ -1,16 +1,18 @@
-#  Jira plugin  #
+# Jira plugin
 
-CLI support for JIRA interaction
+This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
 
-##  Description  ##
+To use it, add `jira` to the plugins array in your zshrc file:
 
-This plugin provides command line tools for interacting with Atlassian's [JIRA](https://www.atlassian.com/software/jira) bug tracking software.
+```zsh
+plugins=(... jira)
+```
 
 The interaction is all done through the web. No local installation of JIRA is necessary.
 
 In this document, "JIRA" refers to the JIRA issue tracking server, and `jira` refers to the command this plugin supplies.
 
-##  Usage  ##
+## Usage
 
 This plugin supplies one command, `jira`, through which all its features are exposed. Most forms of this command open a JIRA page in your web browser.
 
@@ -18,19 +20,19 @@ This plugin supplies one command, `jira`, through which all its features are exp
 
 `jira help` or `jira usage` will print the below usage instructions
 
-| Command       | Description                                               |
-| :------------ | :-------------------------------------------------------- |
-| `jira`        | Performs the default action                               |
-| `jira new`    | Opens a new Jira issue dialogue                           |
-| `jira ABC-123`   | Opens an existing issue                                |
-| `jira ABC-123 m` | Opens an existing issue for adding a comment           |
-| `jira dashboard [rapid_view]` |  Opens your JIRA dashboard              |
-| `jira mine`   | Queries for your own issues                               |
-| `jira tempo`  | Opens your JIRA Tempo                                     |
-| `jira reported [username]`  | Queries for issues reported by a user       |
-| `jira assigned [username]`  | Queries for issues assigned to a user       |
-| `jira branch` | Opens an existing issue matching the current branch name  |
-| `jira help` | Prints usage instructions  |
+| Command                       | Description                                              |
+| :---------------------------- | :------------------------------------------------------- |
+| `jira`                        | Performs the default action                              |
+| `jira new`                    | Opens a new Jira issue dialogue                          |
+| `jira ABC-123`                | Opens an existing issue                                  |
+| `jira ABC-123 m`              | Opens an existing issue for adding a comment             |
+| `jira dashboard [rapid_view]` | Opens your JIRA dashboard                                |
+| `jira mine`                   | Queries for your own issues                              |
+| `jira tempo`                  | Opens your JIRA Tempo                                    |
+| `jira reported [username]`    | Queries for issues reported by a user                    |
+| `jira assigned [username]`    | Queries for issues assigned to a user                    |
+| `jira branch`                 | Opens an existing issue matching the current branch name |
+| `jira help`                   | Prints usage instructions                                |
 
 
 ### Jira Branch usage notes
@@ -43,7 +45,7 @@ This is also checks if the prefix is in the name, and adds it if not, so: "MP-12
 
 
 
-#### Debugging usage  ####
+#### Debugging usage
 
 These calling forms are for developers' use, and may change at any time.
 
@@ -51,7 +53,7 @@ These calling forms are for developers' use, and may change at any time.
 jira dumpconfig   # displays the effective configuration
 ```
 
-##  Setup  ##
+## Setup
 
 The URL for your JIRA instance is set by `$JIRA_URL` or a `.jira_url` file.
 
@@ -68,7 +70,7 @@ echo "https://jira.atlassian.com" >> .jira-url
 
 (Note: The current implementation only looks in the current directory for `.jira-url` and `.jira-prefix`, not up the path, so if you are in a subdirectory of your project, it will fall back to your default JIRA URL. This will probably change in the future though.)
 
-###  Variables  ###
+### Variables
 
 * `$JIRA_URL` - Your JIRA instance's URL
 * `$JIRA_NAME` - Your JIRA username; used as the default user for `assigned`/`reported` searches
@@ -79,6 +81,6 @@ echo "https://jira.atlassian.com" >> .jira-url
 * `$JIRA_TEMPO_PATH` - Your JIRA tempo url path; defaults to "/secure/Tempo.jspa"
 
 
-### Browser ###
+### Browser
 
 Your default web browser, as determined by how `open_command` handles `http://` URLs, is used for interacting with the JIRA instance. If you change your system's URL handler associations, it will change the browser that `jira` uses.
diff --git a/plugins/kube-ps1/README.md b/plugins/kube-ps1/README.md
index dd49eff39..be3c184be 100644
--- a/plugins/kube-ps1/README.md
+++ b/plugins/kube-ps1/README.md
@@ -1,5 +1,4 @@
-kube-ps1: Kubernetes prompt for bash and zsh
-============================================
+# kube-ps1: Kubernetes prompt for bash and zsh
 
 A script that lets you add the current Kubernetes context and namespace
 configured on `kubectl` to your Bash/Zsh prompt strings (i.e. the `$PS1`).
diff --git a/plugins/per-directory-history/README.md b/plugins/per-directory-history/README.md
index 11150b059..2816c11ba 100644
--- a/plugins/per-directory-history/README.md
+++ b/plugins/per-directory-history/README.md
@@ -1,5 +1,4 @@
-per-directory-history plugin
-----------------------------
+# per-directory-history plugin
 
 This plugin adds per-directory history for zsh, as well as a global history,
 and the ability to toggle between them with a keyboard shortcut. This is a
diff --git a/plugins/pipenv/README.md b/plugins/pipenv/README.md
index e78ef0e3b..429b6f186 100644
--- a/plugins/pipenv/README.md
+++ b/plugins/pipenv/README.md
@@ -1,6 +1,6 @@
 # Pipenv
 
-## Installation
+This plugin provides some features to simplify the use of [Pipenv](https://pipenv.pypa.io/) while working on ZSH.
 
 In your `.zshrc` file, add `pipenv` to the plugins section
 
@@ -10,8 +10,6 @@ plugins=(... pipenv ...)
 
 ## Features
 
-This plugin provides some features to simplify the use of Pipenv while working on ZSH.
-
 - Adds completion for pipenv
 - Auto activates and deactivates pipenv shell
 - Adds short aliases for common pipenv commands
diff --git a/plugins/spring/README.md b/plugins/spring/README.md
index 816181326..b93402000 100644
--- a/plugins/spring/README.md
+++ b/plugins/spring/README.md
@@ -1,16 +1,12 @@
 # Spring Boot oh-my-zsh plugin
-oh-my-zsh Spring Boot plugin
 
-## Spring Boot autocomplete plugin
+Adds autocomplete options for all [Spring Boot](https://spring.io/projects/spring-boot) commands.
 
-- Adds autocomplete options for all spring boot commands.
+To use it, add `spring` to the plugins array in your zshrc file:
 
-## Manual Install
-
-     $ cd ~/.oh-my-zsh/plugins
-     $ git clone git@github.com:linux-china/oh-my-zsh-spring-boot-plugin.git spring
-
-Adjust your .zshrc file and add spring to plugins=(...)
+```zsh
+plugins=(... spring)
+```
 
 ## Tips
 
diff --git a/plugins/ssh/README.md b/plugins/ssh/README.md
new file mode 100644
index 000000000..3dd32ec76
--- /dev/null
+++ b/plugins/ssh/README.md
@@ -0,0 +1,16 @@
+# ssh plugin
+
+This plugin provides host completion based off of your `~/.ssh/config` file, and adds
+some utility functions to work with SSH keys.
+
+To use it, add `ssh` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... ssh)
+```
+
+## Functions
+
+- `ssh_rmhkey`: remove host key from known hosts based on a host section name from `.ssh/config`.
+- `ssh_load_key`: load SSH key into agent.
+- `ssh_unload_key`: remove SSH key from agent.
diff --git a/plugins/suse/README.md b/plugins/suse/README.md
index f37ec1695..e1e3aad29 100644
--- a/plugins/suse/README.md
+++ b/plugins/suse/README.md
@@ -1,8 +1,6 @@
 # suse
 
-**Maintainer**: [r-darwish](https://github.com/r-darwish)
-
-Alias for Zypper according to the official Zypper's alias
+Aliases for [Zypper](https://en.opensuse.org/Portal:Zypper) according to the official Zypper's alias
 
 To use it add `suse` to the plugins array in you zshrc file.
 
@@ -10,6 +8,8 @@ To use it add `suse` to the plugins array in you zshrc file.
 plugins=(... suse)
 ```
 
+**Maintainer**: [r-darwish](https://github.com/r-darwish)
+
 ## Main commands
 
 | Alias            | Commands                      | Description                                                    |
@@ -79,6 +79,7 @@ Related: [#9798](https://github.com/ohmyzsh/ohmyzsh/pull/9798).
 | zrr   | `sudo zypper rr`    | remove repositories                      |
 
 ## Services commands
+
 | Alias | Commands           | Description                                                    |
 | ----- | ------------------ | -------------------------------------------------------------- |
 | zas   | `sudo zypper as`   | adds a service specified by URI to the system                  |
@@ -88,6 +89,7 @@ Related: [#9798](https://github.com/ohmyzsh/ohmyzsh/pull/9798).
 | zls   | `zypper ls`        | list services defined on the system                            |
 
 ## Package Locks Management commands
+
 | Alias | Commands         | Description                         |
 | ----- | ---------------- | ----------------------------------- |
 | zal   | `sudo zypper al` | add a package lock                  |
diff --git a/plugins/swiftpm/README.md b/plugins/swiftpm/README.md
index e5b4752e4..babbf4d66 100644
--- a/plugins/swiftpm/README.md
+++ b/plugins/swiftpm/README.md
@@ -1,7 +1,5 @@
 # Swift Package Manager
 
-## Description
-
 This plugin provides a few utilities that make you faster on your daily work with the [Swift Package Manager](https://github.com/apple/swift-package-manager), as well as autocompletion for Swift 5.9.
 
 To start using it, add the `swiftpm` plugin to your `plugins` array in `~/.zshrc`:
diff --git a/plugins/vagrant-prompt/README.md b/plugins/vagrant-prompt/README.md
index dd0ca363b..0720f4bde 100644
--- a/plugins/vagrant-prompt/README.md
+++ b/plugins/vagrant-prompt/README.md
@@ -1,6 +1,33 @@
+# vagrant-prompt
+
 This plugin prompts the status of the Vagrant VMs. It supports single-host and
 multi-host configurations as well.
 
-Look inside the source for documentation about custom variables.
+To use it, add `vagrant-prompt` to the plugins array in your zshrc file:
+
+```zsh
+plugins=(... vagrant-prompt)
+```
+
+**Alberto Re <alberto.re@gmail.com>**
+
+## Usage
+
+To display Vagrant info on your prompt add the `vagrant_prompt_info` to the
+`$PROMPT` or `$RPROMPT` variable in your theme. Example:
+
+```zsh
+PROMPT='%{$fg[$NCOLOR]%}%B%n%b%{$reset_color%}:%{$fg[blue]%}%B%c/%b%{$reset_color%} $(vagrant_prompt_info)$(svn_prompt_info)$(git_prompt_info)%(!.#.$) '
+```
+
+`vagrant_prompt_info` makes use of some custom variables. This is an example
+definition:
 
-Alberto Re <alberto.re@gmail.com>
+```zsh
+ZSH_THEME_VAGRANT_PROMPT_PREFIX="%{$fg_bold[blue]%}["
+ZSH_THEME_VAGRANT_PROMPT_SUFFIX="%{$fg_bold[blue]%}]%{$reset_color%} "
+ZSH_THEME_VAGRANT_PROMPT_RUNNING="%{$fg_no_bold[green]%}●"
+ZSH_THEME_VAGRANT_PROMPT_POWEROFF="%{$fg_no_bold[red]%}●"
+ZSH_THEME_VAGRANT_PROMPT_SUSPENDED="%{$fg_no_bold[yellow]%}●"
+ZSH_THEME_VAGRANT_PROMPT_NOT_CREATED="%{$fg_no_bold[white]%}○"
+```
diff --git a/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh b/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh
index d7c76c3c9..29f4038c5 100644
--- a/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh
+++ b/plugins/vagrant-prompt/vagrant-prompt.plugin.zsh
@@ -1,20 +1,3 @@
-# vim:ft=zsh ts=2 sw=2 sts=2
-#
-# To display Vagrant infos on your prompt add the vagrant_prompt_info to the
-# $PROMPT variable in your theme. Example:
-#
-# PROMPT='%{$fg[$NCOLOR]%}%B%n%b%{$reset_color%}:%{$fg[blue]%}%B%c/%b%{$reset_color%} $(vagrant_prompt_info)$(svn_prompt_info)$(git_prompt_info)%(!.#.$) '
-#
-# `vagrant_prompt_info` makes use of some custom variables. This is an example
-# definition:
-#
-# ZSH_THEME_VAGRANT_PROMPT_PREFIX="%{$fg_bold[blue]%}["
-# ZSH_THEME_VAGRANT_PROMPT_SUFFIX="%{$fg_bold[blue]%}]%{$reset_color%} "
-# ZSH_THEME_VAGRANT_PROMPT_RUNNING="%{$fg_no_bold[green]%}●"
-# ZSH_THEME_VAGRANT_PROMPT_POWEROFF="%{$fg_no_bold[red]%}●"
-# ZSH_THEME_VAGRANT_PROMPT_SUSPENDED="%{$fg_no_bold[yellow]%}●"
-# ZSH_THEME_VAGRANT_PROMPT_NOT_CREATED="%{$fg_no_bold[white]%}○"
-
 function vagrant_prompt_info() {
   local vm_states vm_state
   if [[ -d .vagrant && -f Vagrantfile ]]; then
diff --git a/plugins/vim-interaction/README.md b/plugins/vim-interaction/README.md
index c2b45f1d8..437b48d99 100644
--- a/plugins/vim-interaction/README.md
+++ b/plugins/vim-interaction/README.md
@@ -1,5 +1,13 @@
 # Vim Interaction #
 
+The idea for this script is to give you some decent interaction with a running
+GVim session.  Normally you'll be running around your filesystem doing any
+number of amazing things and you'll need to load some files into GVim for
+editing, inspecting, destruction, or other bits of mayhem.  This script lets you
+do that.
+
+## Usage
+
 The plugin presents a function called `callvim` whose usage is:
 
     usage: callvim [-b cmd] [-a cmd] [file ... fileN]
@@ -9,14 +17,6 @@ The plugin presents a function called `callvim` whose usage is:
       file       The file to edit
       ... fileN  The other files to add to the argslist
 
-## Rationale ##
-
-The idea for this script is to give you some decent interaction with a running
-GVim session.  Normally you'll be running around your filesystem doing any
-number of amazing things and you'll need to load some files into GVim for
-editing, inspecting, destruction, or other bits of mayhem.  This script lets you
-do that.
-
 ## Aliases ##
 
 There are a few aliases presented as well:
diff --git a/plugins/xcode/README.md b/plugins/xcode/README.md
index 27d6a228b..ac79f728d 100644
--- a/plugins/xcode/README.md
+++ b/plugins/xcode/README.md
@@ -1,7 +1,5 @@
 # Xcode
 
-## Description
-
 This plugin provides a few utilities that can help you on your daily use of Xcode and iOS development.
 
 To start using it, add the `xcode` plugin to your `plugins` array in `~/.zshrc`:
diff --git a/plugins/yii2/README.md b/plugins/yii2/README.md
index 345b66eb6..e6c71f23e 100644
--- a/plugins/yii2/README.md
+++ b/plugins/yii2/README.md
@@ -1,7 +1,7 @@
 # Yii2 autocomplete plugin
 
-* Adds autocomplete commands and subcommands for yii.
+Adds autocomplete commands and subcommands for [yii](https://www.yiiframework.com/).
 
 ## Requirements
 
-Autocomplete works from directory where your `yii` file contains.
+Autocomplete works from directory where your `yii` file is contained.
diff --git a/plugins/zsh-interactive-cd/README.md b/plugins/zsh-interactive-cd/README.md
index 4bffbf04a..29812a295 100644
--- a/plugins/zsh-interactive-cd/README.md
+++ b/plugins/zsh-interactive-cd/README.md
@@ -1,5 +1,7 @@
 # zsh-interactive-cd
 
+This plugin provides an interactive way to change directories in zsh using fzf.
+
 ## Demo
 
 ![demo](demo.gif)
@@ -8,7 +10,11 @@
 
 1. Install [fzf](https://github.com/junegunn/fzf) by following its [installation instruction](https://github.com/junegunn/fzf#installation).
 
-2. Source `zsh-interactive-cd.plugin.zsh` in `.zshrc`.
+2. Add `zsh-interactive-cd` to your plugin list in `~/.zshrc`:
+
+   ```zsh
+   plugins=(... zsh-interactive-cd)
+   ```
 
 ## Usage