Merge pull request #502 from CloudCannon/feat/highlight-polish

Final polish for the highlighting feature

docs/content/docs/_index.md

@@ -53,19 +53,6 @@ We can see that a bunch of content was indexed, and Pagefind will be running a p
 
 Loading this in your browser, you should see a search input on your page. Try searching for some content and you will see results appear from your site.
 
-## Highlighting
-
-To highlight the search terms on results page, add the following snippet on every page that has been indexed
-
-```html
-<script src="/pagefind/pagefind-highlight.js"></script>
-<script>
-    new PagefindHighlight();
-<script>
-```
-
-See [Highlighting search terms](/docs/highlighting/) for more information.
-
 The last required step is to run Pagefind after building your site on your CMS or hosting platform. If you're a CloudCannon user, add a [`.cloudcannon/postbuild`](https://cloudcannon.com/documentation/articles/extending-your-build-process-with-hooks/) file containing the npx command above (minus the `--serve` flag). For other platforms, set up an equivalent command to run after your site build — the end goal is that Pagefind will run after every build of your site before it is deployed.
 
 For many use cases, you can stop here and mark it as complete. Or, you can dive deeper into Pagefind and configure it to your liking — check out [Configuring the index](/docs/indexing/) for some next steps.

docs/content/docs/highlight-config.md

@@ -16,13 +16,13 @@ new PagefindHighlight({ markContext: "[data-pagefind-body]" })
 
 The area in which to highlight text. Defaults to `[data-pagefind-body]` if any `[data-pagefind-body]` elements can be found, otherwise `document.body`. This can be a CSS selector string, a DOM element, an array of DOM elements, or a NodeList.
 
-### pagefindQueryParamName
+### highlightParam
 
 ```js
-new PagefindHighlight({ pagefindQueryParamName: "pagefind-highlight" })
+new PagefindHighlight({ highlightParam: "highlight" })
 ```
 
-The name of the query parameter that Pagefind uses to determine which terms to highlight. Defaults to `pagefind-highlight`. If the name is changed here, it *must* be changed in the [`PagefindUI` object](/docs/ui/#highlight-query-param-name) as well.
+The name of the query parameter that Pagefind uses to determine which terms to highlight. This must match the [Pagefind highlightParam config](/docs/search-config/#highlight-query-parameter).
 
 ### markOptions
 

docs/content/docs/highlighting.md

@@ -5,13 +5,47 @@ nav_section: Searching
 weight: 10
 ---
 
-Pagefind allows you to highlight search terms on the result page. To enable this feature, import `/pagefind/pagefind-highlight.js` on the result page and create a new `PagefindHighlight` object.
+Pagefind includes the ability to highlight search terms on the result page.
+
+To enable this feature, first configure Pagefind to insert a query parameter on search results.
+
+## Configuring highlighting via the Default UI
+
+{{< diffcode >}}
+```javascript
+new PagefindUI({
+    element: "#search",
++    highlightParam: "highlight"
+});
+```
+{{< /diffcode >}}
+
+## Configuring highlighting via the JavaScript API
+
+{{< diffcode >}}
+```javascript
+const pagefind = await import("/pagefind/pagefind.js");
+await pagefind.options({
++    highlightParam: "highlight"
+});
+const search = await pagefind.search("static");
+```
+{{< /diffcode >}}
+
+## Enabling highlights on result pages
+
+Once Pagefind is configured to insert query parameters, pages on your site will need to opt-in to highlighting.
+This is something you can implement for your own site by looking at the query parameter, but Pagefind provides a highlighting script for convenience.
+
+To opt-in, import `/pagefind/pagefind-highlight.js` on all pages of your site and create a new `PagefindHighlight` object.
 
 ```html
-<script src="/pagefind/pagefind-highlight.js"></script>
-<script>
-    new PagefindHighlight();
-<script>
+<script type="module">
+    await import('/pagefind/pagefind-highlight.js');
+    new PagefindHighlight({ highlightParam: "highlight" });
+</script>
 ```
 
-To see the options available to PagefindHighlight, see [Highlight Config](/docs/highlight-config).
+Ensure that the `highlightParam` configured here matches the `highlightParam` given to Pagefind when searching.
+
+To see all options available to PagefindHighlight, see [Highlight Config](/docs/highlight-config).

docs/content/docs/search-config.md

@@ -67,6 +67,18 @@ Overrides the bundle directory. In most cases this should be automatically detec
 
 Set the maximum length for generated excerpts. Defaults to `30`.
 
+### Highlight query parameter
+
+```json
+{
+    "highlightParam": "highlight"
+}
+```
+
+If set, Pagefind will add the search term as a query parameter under the same name. 
+
+If using the [Pagefind highlight script](/docs/highlighting/), make sure this is configured to match.
+
 ### Index weight
 
 See [multisite search > weighting](/docs/multisite/#changing-the-weighting-of-individual-indexes)

docs/content/docs/ui.md

@@ -152,19 +152,6 @@ new PagefindUI({
 
 The number of milliseconds to wait after a user stops typing before performing a search. Defaults to `300`. If you wish to disable this, set to `0`.
 
-### Highlight query param name
-
-{{< diffcode >}}
-```javascript
-new PagefindUI({
-    element: "#search",
-+    highlightQueryParamName: 'highlight'
-});
-```
-{{< /diffcode >}}
-
-If the parameter is changed here, it *must* be changed in the [`PagefindHighlight` object](/docs/highlight-config/#pagefindQueryParamName) as well.
-
 ### Translations
 
 {{< diffcode >}}

pagefind/features/highlighting/highlighting_base.feature → pagefind/features/highlighting/highlighting_results.feature

@@ -1,4 +1,4 @@
-Feature: Highlighting Tests
+Feature: Highlighting Result Tests
 
     Background:
         Given I have the environment variables:
@@ -56,7 +56,7 @@ Feature: Highlighting Tests
             <script type="module">
                 await import('/pagefind/pagefind-highlight.js');
                 new PagefindHighlight({
-                pagefindQueryParamName: 'custom-name',
+                highlightParam: 'custom-name',
                 markOptions: {
                         className: 'custom-class',
                         exclude: [

pagefind/features/highlighting/highlighting_search.feature

@@ -0,0 +1,81 @@
+Feature: Highlighting Search Tests
+
+    Background:
+        Given I have the environment variables:
+            | PAGEFIND_SITE | public |
+        Given I have a "public/index.html" file with the body:
+            """
+            <p data-url>Nothing</p>
+            """
+        Given I have a "public/a/index.html" file with the body:
+            """
+            <p>Hello World</p>
+            """
+        Given I have a "public/b/index.html" file with the body:
+            """
+            <h2 id="second">Second</h2>
+            <p>Second Page</p>
+            """
+
+    Scenario: Query parameters can be inserted through the JS API
+        When I run my program
+        Then I should see "Running Pagefind" in stdout
+        Then I should see the file "public/pagefind/pagefind.js"
+        When I serve the "public" directory
+        When I load "/"
+        When I evaluate:
+            """
+            async function() {
+                let pagefind = await import("/pagefind/pagefind.js");
+                await pagefind.options({ highlightParam: "hi" });
+
+                let search = await pagefind.search("world");
+
+                let data = await search.results[0].data();
+                document.querySelector('[data-url]').innerText = data.url;
+            }
+            """
+        Then There should be no logs
+        Then The selector "[data-url]" should contain "/a/?hi=world"
+
+    Scenario: Multiple query parameters are inserted through the JS API
+        When I run my program
+        Then I should see "Running Pagefind" in stdout
+        Then I should see the file "public/pagefind/pagefind.js"
+        When I serve the "public" directory
+        When I load "/"
+        When I evaluate:
+            """
+            async function() {
+                let pagefind = await import("/pagefind/pagefind.js");
+                await pagefind.options({ highlightParam: "hi" });
+
+                let search = await pagefind.search("hello world");
+
+                let data = await search.results[0].data();
+                document.querySelector('[data-url]').innerText = data.url;
+            }
+            """
+        Then There should be no logs
+        Then The selector "[data-url]" should contain "/a/?hi=hello&amp;hi=world"
+
+    Scenario: Query parameters don't conflict with subresult anchors
+        When I run my program
+        Then I should see "Running Pagefind" in stdout
+        Then I should see the file "public/pagefind/pagefind.js"
+        When I serve the "public" directory
+        When I load "/"
+        When I evaluate:
+            """
+            async function() {
+                let pagefind = await import("/pagefind/pagefind.js");
+                await pagefind.options({ highlightParam: "hi" });
+
+                let search = await pagefind.search("second");
+
+                let data = await search.results[0].data();
+                document.querySelector('[data-url]').innerText = data.sub_results[0].url;
+            }
+            """
+        Then There should be no logs
+        Then The selector "[data-url]" should contain "/b/?hi=second#second"

pagefind/features/ui/ui_highlight.feature

@@ -9,14 +9,14 @@ Feature: Base UI Tests
 
     Scenario: Pagefind UI adds highlight query params
         Given I have a "public/index.html" file with the body:
-                """
+            """
                 <div id="search"></div>
                 <script src="/pagefind/pagefind-ui.js"></script>
 
                 <script>
-                    window.pui = new PagefindUI({ element: "#search" });
+                    window.pui = new PagefindUI({ element: "#search", highlightParam: "pagefind-highlight" });
                 </script>
-                """
+            """
         Given I have a "public/cat/index.html" file with the body:
             """
             <h1>hello world</h1>
@@ -53,18 +53,18 @@ Feature: Base UI Tests
             }
             """
         Then There should be no logs
-        Then The selector ".pagefind-ui__result-link[href$='?pagefind-highlight=hello&pagefind-highlight=world%21']" should contain "hello world"
+        Then The selector ".pagefind-ui__result-link[href$='?pagefind-highlight=hello&pagefind-highlight=world']" should contain "hello world"
 
-    Scenario: Pagefind UI does not add highlight query params
+    Scenario: Pagefind UI does not add highlight query params by default
         Given I have a "public/index.html" file with the body:
-                """
+            """
                 <div id="search"></div>
                 <script src="/pagefind/pagefind-ui.js"></script>
 
                 <script>
-                    window.pui = new PagefindUI({ element: "#search", highlightQueryParamName: null });
+                    window.pui = new PagefindUI({ element: "#search" });
                 </script>
-                """
+            """
         Given I have a "public/cat/index.html" file with the body:
             """
             <h1>hello world</h1>
@@ -96,14 +96,14 @@ Feature: Base UI Tests
 
     Scenario: Pagefind UI uses custom highlight query param name
         Given I have a "public/index.html" file with the body:
-                """
+            """
                 <div id="search"></div>
                 <script src="/pagefind/pagefind-ui.js"></script>
 
                 <script>
-                    window.pui = new PagefindUI({ element: "#search", highlightQueryParamName: 'custom-param' });
+                    window.pui = new PagefindUI({ element: "#search", highlightParam: 'custom-param' });
                 </script>
-                """
+            """
         Given I have a "public/cat/index.html" file with the body:
             """
             <h1>hello world</h1>
@@ -132,12 +132,3 @@ Feature: Base UI Tests
             """
         Then There should be no logs
         Then The selector ".pagefind-ui__result-link[href$='?custom-param=hello&custom-param=world']" should contain "hello world"
-        When I evaluate:
-            """
-            async function() {
-                window.pui.triggerSearch("hello world!");
-                await new Promise(r => setTimeout(r, 1500)); // TODO: await el in humane
-            }
-            """
-        Then There should be no logs
-        Then The selector ".pagefind-ui__result-link[href$='?custom-param=hello&custom-param=world%21']" should contain "hello world"

pagefind/features/ui/ui_hooks.feature

@@ -13,8 +13,7 @@ Feature: UI Hooks
             <script>
                 window.pui = new PagefindUI({
                     element: "#search",
-                    processTerm: (t) => t.replace("word", "search"),
-                    highlightQueryParamName: null
+                    processTerm: (t) => t.replace("word", "search")
                 });
             </script>
             """