Docs: clarify search configuration patterns (#11076)

Closes #11060

Author: stsewd

docs/user/config-file/v2.rst

@@ -657,13 +657,13 @@ Set a custom search rank over pages matching a pattern.
 :Type: ``map`` of patterns to ranks
 :Default: ``{}``
 
-Patterns are matched against the final html pages produced by the build
-(you should try to match `index.html`, not `docs/index.rst`).
-Patterns can include some special characters:
+Patterns are matched against the relative paths of the HTML files produced by the build,
+you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
+Patterns can include one or more of the following special characters:
 
-- ``*`` matches everything
-- ``?`` matches any single character
-- ``[seq]`` matches any character in ``seq``
+- ``*`` matches everything, including slashes.
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
 The rank can be an integer number between -10 and 10 (inclusive).
 Pages with a rank closer to -10 will appear further down the list of results,
@@ -685,8 +685,10 @@ check :ref:`config-file/v2:search.ignore`.
        # Match all files under the api/v1 directory
        api/v1/*: -5
 
-       # Match all files that end with tutorial.html
-       '*/tutorial.html': 3
+       # Match all files named guides.html,
+       # two patterns are needed to match both the root and nested files.
+       'guides.html': 3
+       '*/guides.html': 3
 
 .. note::
 
@@ -706,13 +708,13 @@ Paths matched will not be included in search results.
 :Type: ``list`` of patterns
 :Default: ``['search.html', 'search/index.html', '404.html', '404/index.html']``
 
-Patterns are matched against the relative path of html files produced by the build
-(you should try to match `index.html`, not `docs/index.rst`).
-Patterns can include some special characters:
+Patterns are matched against the relative paths of the HTML files produced by the build,
+you should try to match ``index.html``, not ``docs/index.rst``, nor ``/en/latest/index.html``.
+Patterns can include one or more of the following special characters:
 
-- ``*`` matches everything
-- ``?`` matches any single character
-- ``[seq]`` matches any character in ``seq``
+- ``*`` matches everything (including slashes).
+- ``?`` matches any single character.
+- ``[seq]`` matches any character in ``seq``.
 
 .. code-block:: yaml
 
@@ -726,7 +728,9 @@ Patterns can include some special characters:
         # Ignore all files under the search/ directory
         - search/*
 
-        # Ignore all files named ref.html nested inside one or more sub-folders
+        # Ignore all files named ref.html,
+        # two patterns are needed to match both the root and nested files.
+        - 'ref.html'
         - '*/ref.html'
 
 .. code-block:: yaml