1/** From https://github.com/CloudCannon/pagefind/blob/production-docs/pagefind_web_js/types/index.d.ts */
  2
  3/** Global index options that can be passed to pagefind.options() */
  4export type PagefindIndexOptions = {
  5  /** Overrides the URL path that Pagefind uses to load its search bundle */
  6  basePath?: string;
  7  /** Appends the given baseURL to all search results. May be a path, or a full domain */
  8  baseUrl?: string;
  9  /** The maximum length of excerpts that Pagefind should generate for search results. Default to 30 */
 10  excerptLength?: number;
 11  /**
 12   * Multiply all rankings for this index by the given weight.
 13   *
 14   * Only applies in multisite setups, where one site should rank higher or lower than others.
 15   */
 16  indexWeight?: number;
 17  /**
 18   * Merge this filter object into all search queries in this index.
 19   *
 20   * Only applies in multisite setups.
 21   */
 22  mergeFilter?: object;
 23  /**
 24   * If set, will ass the search term as a query parameter under this key, for use with Pagefind's highlighting script.
 25   */
 26  highlightParam?: string;
 27  language?: string;
 28  /**
 29   * Whether an instance of Pagefind is the primary index or not (for multisite).
 30   *
 31   * This is set for you automatically, so it is unlikely you should set this directly.
 32   */
 33  primary?: boolean;
 34  /**
 35   * Provides the ability to fine tune Pagefind's ranking algorithm to better suit your dataset.
 36   */
 37  ranking?: PagefindRankingWeights;
 38};
 39
 40export type PagefindRankingWeights = {
 41  /**
 42            Controls page ranking based on similarity of terms to the search query (in length).
 43            Increasing this number means pages rank higher when they contain words very close to the query,
 44            e.g. if searching for `part` then `party` will boost a page higher than one containing `partition`.
 45            Minimum value is 0.0, where `party` and `partition` would be viewed equally.
 46        */
 47  termSimilarity?: number;
 48  /**
 49            Controls how much effect the average page length has on ranking.
 50            Maximum value is 1.0, where ranking will strongly favour pages that are shorter than the average page on the site.
 51            Minimum value is 0.0, where ranking will exclusively look at term frequency, regardless of how long a document is.
 52        */
 53  pageLength?: number;
 54  /**
 55            Controls how quickly a term saturates on the page and reduces impact on the ranking.
 56            Maximum value is 2.0, where pages will take a long time to saturate, and pages with very high term frequencies will take over.
 57            As this number trends to 0, it does not take many terms to saturate and allow other paramaters to influence the ranking.
 58            Minimum value is 0.0, where terms will saturate immediately and results will not distinguish between one term and many.
 59        */
 60  termSaturation?: number;
 61  /**
 62            Controls how much ranking uses term frequency versus raw term count.
 63            Maximum value is 1.0, where term frequency fully applies and is the main ranking factor.
 64            Minimum value is 0.0, where term frequency does not apply, and pages are ranked based on the raw sum of words and weights.
 65            Values between 0.0 and 1.0 will interpolate between the two ranking methods.
 66            Reducing this number is a good way to boost longer documents in your search results, as they no longer get penalized for having a low term frequency.
 67         */
 68  termFrequency?: number;
 69};
 70
 71/** Options that can be passed to pagefind.search() */
 72export type PagefindSearchOptions = {
 73  /** If set, this call will load all assets but return before searching. Prefer using pagefind.preload() instead */
 74  preload?: boolean;
 75  /** Add more verbose console logging for this search query */
 76  verbose?: boolean;
 77  /** The set of filters to execute with this search. Input export type  is extremely flexible, see the filtering docs for details */
 78  filters?: object;
 79  /** The set of sorts to use for this search, instead of relevancy */
 80  sort?: object;
 81};
 82
 83/** Filter counts returned from pagefind.filters(), and alongside results from pagefind.search() */
 84export type PagefindFilterCounts = Record<string, Record<string, number>>;
 85
 86/** The main results object returned from a call to pagefind.search() */
 87export type PagefindSearchResults = {
 88  /** All pages that match the search query and filters provided */
 89  results: PagefindSearchResult[];
 90  /** How many results would there have been if you had omitted the filters */
 91  unfilteredResultCount: number;
 92  /** Given the query and filters provided, how many remaining results are there under each filter? */
 93  filters: PagefindFilterCounts;
 94  /** If the searched filters were removed, how many total results for each filter are there? */
 95  totalFilters: PagefindFilterCounts;
 96  /** Information on how long it took Pagefind to execute this query */
 97  timings: {
 98    preload: number;
 99    search: number;
100    total: number;
101  };
102};
103
104/** A single result from a search query, before actual data has been loaded */
105export type PagefindSearchResult = {
106  /** Pagefind's internal ID for this page, unique across the site */
107  id: string;
108  /** Pagefind's internal score for your query matching this page, that is used when ranking these results */
109  score: number;
110  /** The locations of all matching words in this page */
111  words: number[];
112  /**
113   * Calling data() loads the final data fragment needed to display this result.
114   *
115   * Only call this when you need to display the data, rather than all at once.
116   * (e.g. one page as a time, or in a scroll listener)
117   * */
118  data: () => Promise<PagefindSearchFragment>;
119};
120
121/** The useful data Pagefind provides for a search result */
122export type PagefindSearchFragment = {
123  /** Pagefind's processed URL for this page. Will include the baseUrl if configured */
124  url: string;
125  /** Pagefind's unprocessed URL for this page */
126  raw_url?: string;
127  /** The full processed content text of this page */
128  content: string;
129  /** Internal export type  — ignore for now */
130  raw_content?: string;
131  /** The processed excerpt for this result, with matching terms wrapping in `<mark>` elements */
132  excerpt: string;
133  /**
134   * What regions of the page matched this search query?
135   *
136   * Precalculates based on h1->6 tags with IDs, using the text between each.
137   */
138  sub_results: PagefindSubResult[];
139  /** How many total words are there on this page? */
140  word_count: number;
141  /** The locations of all matching words in this page */
142  locations: number[];
143  /**
144   * The locations of all matching words in this page,
145   * paired with data about their weight and relevance to this query
146   */
147  weighted_locations: PagefindWordLocation[];
148  /** The filter keys and values this page was tagged with */
149  filters: Record<string, string[]>;
150  /** The metadata keys and values this page was tagged with */
151  meta: Record<string, string>;
152  /**
153   * The raw anchor data that Pagefind used to generate sub_results.
154   *
155   * Contains _all_ elements that had IDs on the page, so can be used to
156   * implement your own sub result calculations with different semantics.
157   */
158  anchors: PagefindSearchAnchor[];
159};
160
161/** Data for a matched section within a page */
162export type PagefindSubResult = {
163  /**
164   * Title of this sub result — derived from the heading content.
165   *
166   * If this is a result for the section of the page before any headings with IDs,
167   * this will be the same as the page's meta.title value.
168   */
169  title: string;
170  /**
171   * Direct URL to this sub result, comprised of the page's URL plus the hash string of the heading.
172   *
173   * If this is a result for the section of the page before any headings with IDs,
174   * this will be the same as the page URL.
175   */
176  url: string;
177  /** The locations of all matching words in this segment */
178  locations: number[];
179  /**
180   * The locations of all matching words in this segment,
181   * paired with data about their weight and relevance to this query
182   */
183  weighted_locations: PagefindWordLocation[];
184  /** The processed excerpt for this segment, with matching terms wrapping in `<mark>` elements */
185  excerpt: string;
186  /**
187   * Raw data about the anchor element associated with this sub result.
188   *
189   * The omission of this field means this sub result is for text found on the page
190   * before the first heading that had an ID.
191   */
192  anchor?: PagefindSearchAnchor;
193};
194
195/** Information about a matching word on a page */
196export type PagefindWordLocation = {
197  /** The weight that this word was originally tagged as */
198  weight: number;
199  /**
200   * An internal score that Pagefind calculated for this word.
201   *
202   * The absolute value is somewhat meaningless, but the value can be used
203   * in comparison to other values in this set of search results to perform custom ranking.
204   */
205  balanced_score: number;
206  /**
207   * The index of this word in the result content.
208   *
209   * Splitting the content key by whitespacing and indexing by this number
210   * will yield the correct word.
211   */
212  location: number;
213};
214
215/** Raw data about elements with IDs that Pagefind encountered when indexing the page */
216export type PagefindSearchAnchor = {
217  /** What element export type  was this anchor? e.g. `h1`, `div` */
218  element: string;
219  /** The raw id="..." attribute contents of the element */
220  id: string;
221  /**
222   * The text content of this element.
223   *
224   * In order to prevent repeating most of the page data for every anchor,
225   * Pagefind will only take top level text nodes, or text nodes nested within
226   * inline elements such as <a> and <span>.
227   */
228  text?: string;
229  /**
230   * The position of this anchor in the result content.
231   * Splitting the content key by whitespacing and indexing by this number
232   * will yield the first word indexed after this element's ID was found.
233   */
234  location: number;
235};