diff --git a/doc_src/cmds/prompt_hostname.rst b/doc_src/cmds/prompt_hostname.rst
new file mode 100644
index 000000000..a8842c429
--- /dev/null
+++ b/doc_src/cmds/prompt_hostname.rst
@@ -0,0 +1,27 @@
+.. _cmd-prompt_hostname:
+
+prompt_hostname - print the hostname, shortened for use in the prompt
+=====================================================================
+
+Synopsis
+--------
+
+::
+
+    function fish_prompt
+        echo -n (whoami)@(prompt_hostname) (prompt_pwd) '$ '
+    end
+
+Description
+-----------
+
+``prompt_hostname`` prints a shortened version the current hostname for use in the prompt. It will print just the first component of the hostname, everything up to the first dot.
+
+Examples
+--------
+
+::
+
+    # The machine's full hostname is foo.bar.com
+    >_ prompt_hostname
+    foo
diff --git a/doc_src/commands.rst b/doc_src/commands.rst
index ca4ddb67f..d8d8bfeb8 100644
--- a/doc_src/commands.rst
+++ b/doc_src/commands.rst
@@ -72,6 +72,7 @@ Some helper functions, often to give you information for use in your prompt:
 - :ref:`fish_status_to_signal <cmd-fish_status_to_signal>` to give a signal name from a return status.
 - :ref:`prompt_pwd <cmd-prompt_pwd>` to give the current directory in a nicely formatted and shortened way.
 - :ref:`prompt_login <cmd-prompt_login>` to describe the current login, with user and hostname, and to explain if you are in a chroot or connected via ssh.
+- :ref:`prompt_hostname <cmd-prompt_hostname>` to give the hostname, shortened for use in the prompt.
 - :ref:`fish_is_root_user <cmd-fish_is_root_user>` to check if the current user is an administrator user like root.
 - :ref:`fish_add_path <cmd-fish_add_path>` to easily add a path to $PATH.
 - :ref:`alias <cmd-alias>` to quickly define wrapper functions ("aliases").
diff --git a/doc_src/fish_for_bash_users.rst b/doc_src/fish_for_bash_users.rst
index aff97ddfd..785f9306d 100644
--- a/doc_src/fish_for_bash_users.rst
+++ b/doc_src/fish_for_bash_users.rst
@@ -292,15 +292,15 @@ and a rough fish equivalent::
       set -l prompt_symbol '$'
       fish_is_root_user; and set prompt_symbol '#'
 
-      echo -s $hostname (set_color blue) (prompt_pwd) \
+      echo -s (prompt_hostname) (set_color blue) (prompt_pwd) \
       (set_color yellow) $prompt_symbol (set_color normal)
   end
 
 This shows a few differences:
 
 - Fish provides :ref:`set_color <cmd-set_color>` to color text. It can use the 16 named colors and also RGB sequences (so you could also use ``set_color 5555FF``)
-- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is simply a function, so you can use variables like ``$hostname``.
-- Fish offers helper functions for adding things to the prompt, like :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>` for adding a display for common version control systems (git, mercurial, svn) and :ref:`prompt_pwd <cmd-prompt_pwd>` for showing a shortened $PWD (the user's home directory becomes ``~`` and any path component is shortened). 
+- Instead of introducing specific escapes like ``\h`` for the hostname, the prompt is simply a function. To achieve the effect of ``\h``, fish provides helper functions like :ref:`prompt_hostname <cmd-prompt_hostname>`, which prints a shortened version of the hostname.
+- Fish offers other helper functions for adding things to the prompt, like :ref:`fish_vcs_prompt <cmd-fish_vcs_prompt>` for adding a display for common version control systems (git, mercurial, svn), and :ref:`prompt_pwd <cmd-prompt_pwd>` for showing a shortened ``$PWD`` (the user's home directory becomes ``~`` and any path component is shortened).
 
 The default prompt is reasonably full-featured and its code can be read via ``type fish_prompt``.
 
diff --git a/share/functions/prompt_hostname.fish b/share/functions/prompt_hostname.fish
index 225f437c7..93eb3b104 100644
--- a/share/functions/prompt_hostname.fish
+++ b/share/functions/prompt_hostname.fish
@@ -1,4 +1,3 @@
-function prompt_hostname
-    # return the short hostname only by default (#4804)
+function prompt_hostname --description 'Print the hostname, shortened for use in the prompt'
     string replace -r "\..*" "" $hostname
 end