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: