Search Results Tag

Documentation Search provides a {{ documentation:results }} Antlers tag, which behaves similarly to Statamic's search tag. The documentation results tag adds the following capabilities to Statamic's default search tag:

• Related search results can be grouped together,

• Query transformers are applied to user search queries,

• Additional templating options

While the documentation:results tag is similar to the core Statamic tag, creating search result pages using it is slightly different. The most notable difference is that each search result will always return an array of items.

The first item in the items array will correspond to the primary result for the current search result. If the group_results parameter has been set to true, the items array might contain more than one item. Each subsequent item in the array will be another relevant search result from the same entry.

#Available Variables

When using the documentation:results tag you will have access to all the values you've configured within the search index's fields array. If you have added all of Documentation Search's specific fields to your configuration, you will also have access to the following:

• search_title: The title for the index entry. If an entry contains on sections, or the index entry is for an entry's leading content, this will match the title of the entry itself. For each subsequent section of an entry (based on headings), this will contain the heading's inner text.

• search_url: The link to either the entry, in the case of the entry's leading content, or a # link to an individual section. Links to individual sections is based on how your site's permalinks have been configured.

• search_content: Contains the modified content for the index entry. The documentation search provider will attempt to normalize the inner text of different element types, and combine it into a sensible string for you.

• origin_title: This will contain the title of the entry itself, even for indexed sections.

• origin_url: This will contain the URL of the entry itself, even for indexed sections.

• is_root: Indicates if the current index entry is for the entry itself, or for a sub-section.

• additional_context: An additional string that can be indexed to help surface search results. As an example, custom documentation search transformers can add additional information to this value.

• code_samples: An array of code samples discovered when indexing each section.

#Rendering Grouped Search Results

For example, we could implement a simple Antlers template to show the primary search result as well as a "Other results from this page" list below each search result:

 1{{ documentation:results index="docs" paginate="5" as="results" group_results="true" }}
 2    {{ results }}
 3        {{ items.0 }}
 4        <div class="">
 5            <div class="flex">
 6                <h3 class="font-bold text-blue-700">
 7                    <a href="{{ search_url }}" title="{{ search_title | entities }}">{{ search_title }}</a>
 8                    {{ if !is_root }}
 9                    <span class="font-thin text-slate-400">/</span>
10 
11                    <a href="{{ origin_url }}" title="{{ origin_title | entities }}">{{ origin_title | safe_truncate(25, '...') /}}</a>
12                    {{ /if }}
13                </h3>
14            </div>
15            <p class="text-green-600">{{ search_url }}</p>
16            <p>{{ search_content | radius_excerpt(get.q, 250) | safe_truncate(250, '...') | mark }}</p>
17        </div>
18        {{ /items.0 }}
19 
20        {{ if items | count > 1 }}
21        <div class="ml-6">
22            <p class="text-slate-700">Other results from this page</p>
23            <ul class="my-2">
24                {{ items offset="1" }}
25                    <li class="text-blue-700"><a href="{{ search_url }}" title="{{ search_title | entities }}">{{ search_title }}</a></li>
26                {{ /items }}
27            </ul>
28        </div>
29        {{ /if }}
30    {{ /results }}
31{{ /documentation:results }}

#Rendering "Normal" Search Results

To render a more traditional Statamic search results page, where each result appears as its own item, we can set the group_results parameter to false, and only consider the first item in each result's items array:

 1{{ documentation:results index="docs" paginate="5" as="results" group_results="false" }}
 2    {{ results }}
 3        {{ items.0 }}
 4        <div class="">
 5            <div class="flex">
 6                <h3 class="font-bold text-blue-700">
 7                    <a href="{{ search_url }}" title="{{ search_title | entities }}">{{ search_title }}</a>
 8                    {{ if !is_root }}
 9                    <span class="font-thin text-slate-400">/</span>
10 
11                    <a href="{{ origin_url }}" title="{{ origin_title | entities }}">{{ origin_title | safe_truncate(25, '...') /}}</a>
12                    {{ /if }}
13                </h3>
14            </div>
15            <p class="text-green-600">{{ search_url }}</p>
16            <p>{{ search_content | radius_excerpt(get.q, 250) | safe_truncate(250, '...') | mark }}</p>
17        </div>
18        {{ /items.0 }}
19    {{ /results }}
20{{ /documentation:results }}

#Rendering Code Samples in Search Results

The documentation search indexer will collect code samples and store them within the index entry. The documentation:results makes these available as a code_samples array for each item. Each discovered code sample will contain the following variables:

• lang: The detected code sample language. This is determined by looking at common lang- or language- CSS class names or data attributes.

• sample: The content of the code sample.

 1{{ documentation:results index="docs" paginate="5" as="results" group_results="false" }}
 2    {{ results }}
 3        {{ items.0 }}
 4            {{# Render the first code sample for the item. #}}
 5            {{ if code_samples | count > 0 }}
 6                <div class="ml-6 prose prose-sm dark:prose-invert">
 7                    {{ code_samples.0 }}
 8                        <pre class="language-{{ lang }}"><code>{{ sample | entities }}</code></pre>
 9                    {{ /code_samples.0 }}
10                </div>
11            {{ /if }}
12        {{ /items.0 }}
13    {{ /results }}
14{{ /documentation:results }}

#Search Tag Parameters

The documentation:results tag shares many parameters with Statamic's search:results tag. The following parameters can be used when working with the documentation:results search tag:

Parameter	Data Type	Description
index	string	The search index to query. Default: default.
query	string	The query string parameter that contains the search term. Default: q.
site	string	The site to search within. Defaults to the current site. All sites can be searched by supplying a wildcard * value.
limit	integer	Limits the total number of results to search.
offset	integer	Skips the specified number of search results.
as	string	Allows you to rename the array the search results are contained in. Default: results.
for	string	Forces a custom search query, overriding the query parameter.
supplement_data	boolean	When true, all non-indexed content will be made available from the returned entries.
paginate	number	Indicates the results should be paginated. When a number is supplied, it will determine the page size.
group_results	boolean	When set to true, the search results will be grouped when multiple results are returned for a single entry.