Index Configuration

Configuring a search index using Documentation Search is largely the same as configuring a regular Statamic search index. The only things to consider when configuring additional search indexes utilizing Documentation Search's search provider is the inclusion of additional fields within your index and using the correct provider prefix.

#The Documentation Search Provider

The documentation search provider extends the capabilities of Statamic's entries provider. Specifically, it does the following:

• Provides advanced methods for modifying the content that will be indexed through the use of custom Antlers templates,

• Splits larger entries into individual index entries, allowing us to surface sections of a page in search results,

• Provides additional variables to help create advanced search result pages

When configuring a normal collection index, we might use the following:

 1<?php
 2 
 3return [
 4 // ...
 5 
 6 'indexes' => [
 7 'docs' => [
 8 'driver' => 'local',
 9 'searchables' => 'collection:documentation',
10 ],
11 ],
12 
13 // ...
14];

At the most basic level, the only thing we would need to change to use the documentation search provider is to swap the collection: prefix inside the searchables value with docs::

 1<?php
 2 
 3return [
 4 // ...
 5 
 6 'indexes' => [
 7 'docs' => [
 8 'driver' => 'local',
 9 'searchables' => 'docs:blog',
10 ],
11 ],
12 
13 // ...
14];

#Additional Index Fields

The documentation search provider makes many additional fields available for use when building the search results template. The following should be added to your fields configuration when using the docs: search provider:

• search_title: The title for the index entry. If an entry contains no 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 the entry, in the case of the entry's leading content, or a # link to an individual section. Links to individual sections are 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.

• origin_title: This will contain the entry's title, even for indexed sections.

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

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

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

• code_samples: An array of code samples discovered when indexing each section. If you do not plan on using code samples in your search result templates you should not include them in your index for performance reasons when you have a large amount of entries with a lot of code samples.

 1<?php
 2 
 3return [
 4 
 5 // ...
 6 
 7 'indexes' => [
 8 
 9 'docs' => [
10 'driver' => 'local',
11 'searchables' => [
12 'docs:documentation',
13 ],
14 'fields' => [
15 'title',
16 'id',
17 
18 // Additional fields
19 'search_title',
20 'search_url',
21 'search_content',
22 'origin_title',
23 'origin_url',
24 'is_root',
25 'additional_context',
26 'code_samples',
27 ],
28 // ...
29 ],
30 ],
31];

#Query and Search Transformers

⚠️ Read first before continuing: The documentation search provider provides additional query and search transformer concepts. While these features have a similar name to Statamic's search transformers, they behave slightly differently.

The documentation search provides two types of search transformers:

• Document Transformers: These transformers can add additional context to the entry or section before it is added to the search index. For example, we could use a document transformer to insert additional keywords using a dictionary of similar terms but not have those values appear in the search result text.

• Query Transformers: Query transformers behave very similarly to Documentation Search's document transformers, except they are applied to a user's search query when making searches using the {{ documentation:results }} Antlers tag.

These additional transformers can be configured within the config/statamic/search.php configuration file for the specific index by adding class references to the document_transformers and query_transformers configuration arrays.

An example index configuration for Documentation Search might look like this:

 1<?php
 2 
 3return [
 4 
 5 // ...
 6 
 7 'indexes' => [
 8 
 9 'docs' => [
10 'driver' => 'local',
11 'searchables' => [
12 'docs:documentation',
13 ],
14 'fields' => [
15 'title',
16 'id',
17 'search_title',
18 'search_url',
19 'search_content',
20 'origin_title',
21 'origin_url',
22 'is_root',
23 'additional_context',
24 'code_samples',
25 ],
26 'header_threshold' => 1,
27 'skip_headers' => [
28 ],
29 'document_transformers' => [
30 \Stillat\DocumentationSearch\Indexing\Transformers\Document\SoundexTransformer::class,
31 ],
32 'query_transformers' => [
33 \Stillat\DocumentationSearch\Indexing\Transformers\Query\SoundexTransformer::class,
34 ],
35 ],
36 
37 ],
38 
39 // ...
40 
41];

#Heading Thresholds and Ignoring Headers

The documentation search provider offers a few extra configuration options that will help control how content is indexed:

• header_threshold: The number of headers that must appear within an entry's content before it can be split into multiple sections. Entries that do not contain enough headers to meet this threshold will be added as a single index entry.

• skip_headers: A list of headings that the indexer should skip. It is helpful if you have any "Wrapping Up," "In Conclusion," or similar headings you don't want to be indexed.

As an example, if we wanted to ensure an entry has at least two sections, as well as skip the "In Conclusion" and "Wrapping Up" headings, we could configure our index like so:

 1<?php
 2 
 3return [
 4 
 5 // ...
 6 
 7 'indexes' => [
 8 
 9 'docs' => [
10 'driver' => 'local',
11 'searchables' => [
12 'docs:documentation',
13 ],
14 'fields' => [
15 // ...
16 ],
17 'header_threshold' => 2,
18 'skip_headers' => [
19 'in conclusion',
20 'wrapping up',
21 ],
22 // ...
23 ],
24 
25 ],
26 
27 // ...
28 
29];

If you need to render headings to the page but do not want them to be considered when creating sections during indexing, you may add the data-indexer="ignore" attribute to your headings.

When the indexer encounters a heading like this, it will be treated as any other text element and not create a new section:

1<h3 data-indexer="ignore">My awesome heading</h3>

#Rendering Content for the Search Index

The documentation search provider utilizes Antlers templates to provide data to the search indexer. Doing so dramatically simplifies the process of splitting entries into documents based on headings, especially for more complicated fieldtypes like Bard.

The indexer will look for templates within your site's resources/views/documentation-search/ directory. The indexer will first attempt to locate a collection and blueprint specific index template at the following location:

1resources/views/documentation-search/<collection_handle>/<blueprint_handle>.antlers.html

If a specific template is not found, it will then look for a resources/views/documentation-search/_default.antlers.html. If no template can be found, the indexer will ignore the entry.

1resources/views/documentation-search/<collection_handle>/_default.antlers.html

The documentation search provider expects the template to produce HTML, with all headings in-place. When outputting headings for sections within the document, please be sure to output headings that match your site's permalinks structure.

Here are some tips and considerations when outputting HTML for the search indexer:

• Avoid outputting a top-level <h1 /> element. The indexer will create one automatically to capture the document's leading content

• The indexer renders the template with the entry data, and does not make requests to your site

• Do not output any extra HTML that is not needed for the indexer, such as sidebars, headings, footers, etc.