Update documentation

Author: sylhare

README.md

@@ -103,24 +103,41 @@ Here is a table for the available options, usage questions, troubleshooting & gu
 ### templateMiddleware (Function) [optional]
 
 A function that will be called whenever a match in the template is found.
-It gets passed the current property name, property value, and the template.
+It gets passed the current property name, property value, template, query, and match information.
 If the function returns a non-undefined value, it gets replaced in the template.
 
-This can be potentially useful for manipulating URLs etc.
+**New Interface:**
+```js
+templateMiddleware(prop, value, template, query?, matchInfo?)
+```
 
-Example:
+- `prop`: The property name being processed from the JSON data.
+- `value`: The property value
+- `template`: The template string
+- `query`: The search query (optional)
+- `matchInfo`: Array of match information objects with start/end positions and match types (optional)
 
+This can be useful for manipulating URLs, highlighting search terms, or custom formatting.
+
+**Basic Example:**
 ```js
 SimpleJekyllSearch({
   // ...other config
-  templateMiddleware: function(prop, value, template) {
-    if (prop === 'bar') {
-      return value.replace(/^\//, '')
+  searchResultTemplate: '<li>{title}</li>',
+  templateMiddleware: function(prop, value, template, query, matchInfo) {
+    if (prop === 'title') {
+      return value.toUpperCase()
     }
   },
 })
 ```
 
+**How it works:**
+- Template: `'<li>{title}</li>'`
+- When processing `{title}`: `prop = 'title'`, `value = 'my post'` → returns `'MY POST'`
+- Final result: `'<li>MY POST</li>'`
+
+
 ### sortMiddleware (Function) [optional]
 
 A function that will be used to sort the filtered results.
@@ -139,3 +156,33 @@ SimpleJekyllSearch({
   },
 })
 ```
+
+### Built-in Highlight Middleware (Function) [optional]
+
+Simple-Jekyll-Search now includes built-in highlighting functionality that can be easily integrated:
+
+```js
+import { createHighlightTemplateMiddleware } from 'simple-jekyll-search/middleware';
+
+SimpleJekyllSearch({
+  // ...other config
+  templateMiddleware: createHighlightTemplateMiddleware({
+    className: 'search-highlight',  // CSS class for highlighted text
+    maxLength: 200,                 // Maximum length of highlighted content
+    contextLength: 30               // Characters of context around matches
+  }),
+})
+```
+
+**Highlight Options:**
+- `className`: CSS class name for highlighted spans (default: 'search-highlight')
+- `maxLength`: Maximum length of content to display (truncates with ellipsis)
+- `contextLength`: Number of characters to show around matches when truncating
+
+**CSS Styling:**
+```css
+.search-highlight {
+  background-color: yellow;
+  font-weight: bold;
+}
+```

docs/get-started.md

@@ -65,7 +65,7 @@ Customize SimpleJekyllSearch by passing in your configuration options:
     searchResultTemplate: '<li><a href="{url}?query={query}" title="{desc}">{title}</a></li>',
     noResultsText: 'No results found',
     limit: 10,
-    fuzzy: true,
+    strategy: 'fuzzy',
     exclude: ['Welcome']
   })
 </script>

tests/Repository.test.ts

@@ -1,6 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { Repository } from '../src/Repository';
-import { SearchResult } from '../src/utils/types';
 
 interface TestElement {
   title: string;
@@ -95,7 +94,7 @@ describe('Repository', () => {
     expect(repository.search('almostbar')).toEqual([]);
   });
 
-  it('excludes items from search #2', () => {
+  it('sorts search results alphabetically by title', () => {
     repository.setOptions({
       sortMiddleware: (a: TestElement, b: TestElement) => {
         return a.title.localeCompare(b.title);
@@ -108,23 +107,90 @@ describe('Repository', () => {
     expect(results[2]).toMatchObject(loremElement);
   });
 
+  it('uses default NoSort when no sortMiddleware provided', () => {
+    const results = repository.search('r');
+    expect(results).toHaveLength(3);
+    expect(results[0]).toMatchObject(barElement);
+    expect(results[1]).toMatchObject(almostBarElement);
+    expect(results[2]).toMatchObject(loremElement);
+  });
+
+  it('demonstrates README example: custom sorting by section and caption', () => {
+    const testData = [
+      { section: 'Getting Started', caption: 'Installation', title: 'How to install' },
+      { section: 'API Reference', caption: 'Methods', title: 'Available methods' },
+      { section: 'Getting Started', caption: 'Configuration', title: 'How to configure' },
+      { section: 'API Reference', caption: 'Properties', title: 'Object properties' }
+    ];
+    
+    repository.put(testData);
+    repository.setOptions({
+      sortMiddleware: (a: any, b: any) => {
+        const astr = String(a.section) + "-" + String(a.caption);
+        const bstr = String(b.section) + "-" + String(b.caption);
+        return astr.localeCompare(bstr);
+      },
+    });
+    
+    const results = repository.search('How');
+    expect(results).toHaveLength(2);
+    // Should be sorted by section first, then caption
+    expect(results[0].section).toBe('Getting Started');
+    expect(results[0].caption).toBe('Configuration');
+    expect(results[1].section).toBe('Getting Started');
+    expect(results[1].caption).toBe('Installation');
+  });
+
   it('search results should be a clone and not a reference to repository data', () => {
     const query = 'Developer';
-    repository.put(
+    const testData = [
       { name: 'Alice', role: 'Developer' },
-      { name: 'Bob', role: 'Designer' },
-    );
+      { name: 'Bob', role: 'Designer' }
+    ];
+    repository.put(testData);
 
     const results = repository.search(query);
     expect(results).toHaveLength(1);
     expect(results[0]).toMatchObject({ name: 'Alice', role: 'Developer' });
 
-    (results as SearchResult[]).forEach(result => {
+    (results as any[]).forEach(result => {
       result.role = 'Modified Role';
     });
 
     const originalData = repository.search(query);
     expect(originalData).toHaveLength(1);
     expect(originalData[0]).toMatchObject({ name: 'Alice', role: 'Developer' });
   });
+
+  it('demonstrates README sortMiddleware example exactly', () => {
+    // This test matches the exact example from the README
+    const testData = [
+      { section: 'API Reference', caption: 'Properties', title: 'Object properties' },
+      { section: 'Getting Started', caption: 'Installation', title: 'How to install' },
+      { section: 'API Reference', caption: 'Methods', title: 'Available methods' },
+      { section: 'Getting Started', caption: 'Configuration', title: 'How to configure' }
+    ];
+    
+    repository.put(testData);
+    repository.setOptions({
+      sortMiddleware: function(a: any, b: any) {
+        var astr = String(a.section) + "-" + String(a.caption);
+        var bstr = String(b.section) + "-" + String(b.caption);
+        return astr.localeCompare(bstr);
+      },
+    });
+    
+    const results = repository.search('a'); // Search for 'a' to get all results
+    expect(results).toHaveLength(4);
+    
+    // Should be sorted by section first, then caption alphabetically
+    expect(results[0].section).toBe('API Reference');
+    expect(results[0].caption).toBe('Methods');
+    expect(results[1].section).toBe('API Reference');
+    expect(results[1].caption).toBe('Properties');
+    expect(results[2].section).toBe('Getting Started');
+    expect(results[2].caption).toBe('Configuration');
+    expect(results[3].section).toBe('Getting Started');
+    expect(results[3].caption).toBe('Installation');
+  });
 });

tests/Templater.test.ts

@@ -137,4 +137,43 @@ describe('Templater', () => {
     const compiled = templater.compile({ foo: 'bar' });
     expect(compiled).toBe('bar');
   });
+
+  it('demonstrates README example: uppercase title middleware', () => {
+    templater.setOptions({
+      template: '<li>{title}</li>',
+      middleware(prop: string, value: string) {
+        if (prop === 'title') {
+          return value.toUpperCase();
+        }
+        return undefined
+      }
+    });
+
+    const data = { title: 'my post' };
+    const compiled = templater.compile(data);
+    expect(compiled).toBe('<li>MY POST</li>');
+  });
+
+  it('demonstrates multiple property processing with different transformations', () => {
+    templater.setOptions({
+      template: '<li><a href="{url}">{title}</a><p>{desc}</p></li>',
+      middleware(prop: string, value: string) {
+        if (prop === 'url') {
+          return value.replace(/^\//, ''); // Remove leading slash
+        }
+        if (prop === 'title') {
+          return value.toUpperCase();
+        }
+        return undefined;
+      }
+    });
+
+    const data = { 
+      url: '/blog/post', 
+      title: 'my post', 
+      desc: 'description' 
+    };
+    const compiled = templater.compile(data);
+    expect(compiled).toBe('<li><a href="blog/post">MY POST</a><p>description</p></li>');
+  });
 });