diff --git a/plugins/dirhistory/README.md b/plugins/dirhistory/README.md
index 602fc8284..ede9b5410 100644
--- a/plugins/dirhistory/README.md
+++ b/plugins/dirhistory/README.md
@@ -12,19 +12,27 @@ plugins=(... dirhistory)
| Shortcut | Description |
|-----------------------------------|-----------------------------------------------------------|
-| alt + left | Go to previous directory |
-| alt + right | Undo alt + left |
-| alt + up | Move into the parent directory |
-| alt + down | Move into the first child directory by alphabetical order |
+| Alt + Left | Go to previous directory |
+| Alt + Right | Go to next directory |
+| Alt + Up | Move into the parent directory |
+| Alt + Down | Move into the first child directory by alphabetical order |
-NOTE: some terminals might override the ALT+Arrows key bindings (Windows Terminal, for example).
-If these don't work check your terminal settings and change them to a different keyboard shortcut.
+**For macOS: use the Option key (⌥) instead of Alt**.
+
+> NOTE: some terminals might override the Alt + Arrows key bindings (e.g. Windows Terminal).
+> If these don't work check your terminal settings and change them to a different keyboard shortcut.
## Usage
-This plugin allows you to navigate the history of previous current-working-directories using ALT-LEFT and ALT-RIGHT. ALT-LEFT moves back to directories that the user has changed to in the past, and ALT-RIGHT undoes ALT-LEFT. MAC users may alternately use OPT-LEFT and OPT-RIGHT.
+This plugin allows you to navigate the history of previous working directories using Alt + Left
+and Alt + Right. Alt + Left moves to past directories, and
+Alt + Right goes back to recent directories.
-Also, navigate directory **hierarchy** using ALT-UP and ALT-DOWN. (mac keybindings not yet implemented). ALT-UP moves to higher hierarchy (shortcut for 'cd ..'). ALT-DOWN moves into the first directory found in alphabetical order (useful to navigate long empty directories e.g. java packages)
+**NOTE: the maximum directory history size is 30.**
+
+You can also navigate **directory hierarchies** using Alt + Up and Alt + Down.
+Alt + Up moves to the parent directory, while Alt + Down moves into the first
+child directory found in alphabetical order (useful to navigate long empty directories, e.g. Java packages).
For example, if the shell was started, and the following commands were entered:
@@ -35,8 +43,20 @@ cd share
cd doc
```
-Then entering ALT-LEFT at the prompt would change directory from /usr/share/doc to /usr/share, then if pressed again to /usr/, then ~. If ALT-RIGHT were pressed the directory would be changed to /usr/ again.
+the directory stack (`dirs -v`) would look like this:
-After that, ALT-DOWN will probably go to /usr/bin (depends on your /usr structure), ALT-UP will return to /usr, then ALT-UP will get you to /
+```console
+$ dirs -v
+0 /usr/share/doc
+1 /usr/share
+2 /usr
+3 ~
+```
-**Currently the max history size is 30**. The navigation should work for xterm, PuTTY xterm mode, GNU screen, and on MAC with alternate keys as mentioned above.
+then entering Alt + Left at the prompt would change directory from `/usr/share/doc` to `/usr/share`,
+then if pressed again to `/usr`, then `~`. If Alt + Right were pressed the directory would be changed
+to `/usr` again.
+
+After that, Alt + Down will probably go to `/usr/bin` if `bin` is the first directory in alphabetical
+order (depends on your `/usr` folder structure). Alt + Up will return to `/usr`, and once more will get
+you to the root folder (`/`).