diff --git a/docs/reference/cat/alias.asciidoc b/docs/reference/cat/alias.asciidoc
index b9aaaa6eb38a6..25b7094202c26 100644
--- a/docs/reference/cat/alias.asciidoc
+++ b/docs/reference/cat/alias.asciidoc
@@ -7,13 +7,12 @@
 Returns information about currently configured aliases to indices, including
 filter and routing information.
 
-
 [[cat-alias-api-request]]
 ==== {api-request-title}
 
-`GET /_cat/aliases/<alias>`
+`GET _cat/aliases/<alias>`
 
-`GET /_cat/aliases`
+`GET _cat/aliases`
 
 [[cat-alias-api-prereqs]]
 ==== {api-prereq-title}
@@ -26,9 +25,9 @@ for any alias you retrieve.
 ==== {api-path-parms-title}
 
 `<alias>`::
-(Optional, string)
-include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=index-alias]
-
+(Optional, string) Comma-separated list of aliases to retrieve. Supports
+wildcards (`*`). To retrieve all aliases, omit this parameter or use `*` or
+`_all`.
 
 [[cat-alias-api-query-params]]
 ==== {api-query-parms-title}
@@ -47,14 +46,13 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=cat-v]
 
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=expand-wildcards]
 
-
 [[cat-alias-api-example]]
 ==== {api-examples-title}
 
 ////
 Hidden setup for example:
-[source,console]
---------------------------------------------------
+[source,console,id=cat-aliases-example]
+----
 PUT test1
 {
   "aliases": {
@@ -75,25 +73,25 @@ PUT test1
     }
   }
 }
---------------------------------------------------
+----
 ////
 
 [source,console]
---------------------------------------------------
-GET /_cat/aliases?v=true
---------------------------------------------------
+----
+GET _cat/aliases?v=true
+----
 // TEST[continued]
 
 The API returns the following response:
 
 [source,txt]
---------------------------------------------------
+----
 alias  index filter routing.index routing.search is_write_index
 alias1 test1 -      -            -              -
 alias2 test1 *      -            -              -
 alias3 test1 -      1            1              -
 alias4 test1 -      2            1,2            -
---------------------------------------------------
+----
 // TESTRESPONSE[s/[*]/[*]/ non_json]
 
 This response shows that `alias2` has configured a filter, and specific routing