From 3093afe7851edf1d3cdaae8378f953b76a491ea6 Mon Sep 17 00:00:00 2001
From: Santos Gallegos <stsewd@proton.me>
Date: Mon, 29 Jan 2024 18:35:15 -0500
Subject: [PATCH] Docs: clarify search configuration patterns

Closes https://github.com/readthedocs/readthedocs.org/issues/11060
---
 docs/user/config-file/v2.rst | 34 +++++++++++++++++++---------------
 1 file changed, 19 insertions(+), 15 deletions(-)

diff --git a/docs/user/config-file/v2.rst b/docs/user/config-file/v2.rst
index b5538ac396a..61fb4859636 100644
--- a/docs/user/config-file/v2.rst
+++ b/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