From d843a1b5d6bf333fbd874ffd6c23eb56a1593a21 Mon Sep 17 00:00:00 2001 From: "Diego Carrasco G." <557703+dacog@users.noreply.github.com> Date: Fri, 21 Mar 2025 23:30:05 +0100 Subject: [PATCH 1/2] feat(flexsearch_plugin): Enhance FlexSearch plugin to support page indexing and update flexsearch library to v0.8 - Add support for indexing pages alongside posts - Add config options for posts, pages, and drafts indexing - Improve search by including title, content, and tags - Add ESC key to close overlay and Enter key to submit search - Add content type badges in search results - Add analytics tracking via UTM parameter - Update UI and improve error handling - Fix search button and event handler issues --- v8/flexsearch_plugin/CHANGELOG.md | 67 +++ v8/flexsearch_plugin/README.md | 336 ++++++------ v8/flexsearch_plugin/conf.py.sample | 512 +++++++++++++++--- v8/flexsearch_plugin/flexsearch.css | 235 ++++++++ v8/flexsearch_plugin/flexsearch_plugin.plugin | 6 +- v8/flexsearch_plugin/flexsearch_plugin.py | 40 +- v8/flexsearch_plugin/imgs/example_overlay.png | Bin 87214 -> 134898 bytes 7 files changed, 934 insertions(+), 262 deletions(-) create mode 100644 v8/flexsearch_plugin/CHANGELOG.md create mode 100644 v8/flexsearch_plugin/flexsearch.css diff --git a/v8/flexsearch_plugin/CHANGELOG.md b/v8/flexsearch_plugin/CHANGELOG.md new file mode 100644 index 00000000..b252b097 --- /dev/null +++ b/v8/flexsearch_plugin/CHANGELOG.md @@ -0,0 +1,67 @@ +# CHANGELOG - FlexSearch Plugin + +## v0.2 (March 21, 2025) + +### New Features +- **Page Indexing**: Added support for indexing pages in addition to posts by removing the post-only restriction in build_index() +- **Configuration Options**: + - `FLEXSEARCH_INDEX_POSTS` (default: `True`) - Control whether posts are indexed + - `FLEXSEARCH_INDEX_PAGES` (default: `False`) - Control whether pages are indexed + - `FLEXSEARCH_INDEX_DRAFTS` (default: `False`) - Control whether draft content is indexed +- **Content Type Display**: Search results now display content type (post/page) with badges using CSS-styled spans +- **Enhanced Search Index**: + - Improved indexing to include title, content, and tags in search for better relevance + - Created a multi-field search approach: `searchIndex.add(key, data[key].title + " " + data[key].content + data[key].tags + " " + data[key].content)` + - Optional `FLEXSEARCH_OVERLAY` version available with advanced features (not enabled by default) +- **Basic UI Improvements**: + - Better handling of search results with clear formatting and type badges + - Support for both overlay and inline result display options +- **Keyboard Shortcuts**: + - ESC key to close search overlay via global event listener + - Enter key support for search submission with preventDefault() to avoid form submission +- **Tracking**: Added `?utm_source=internal_search` to result URLs for analytics tracking +- **Updated Libraries**: Using the latest FlexSearch v0.8.0 from CDN with minified bundle + +### Improvements +- Added console logging for easier debugging +- Upgraded search index structure to include tags +- Better structured code with improved organization +- Two available search implementations: + - Simple implementation (FLEXSEARCH_EXTEND) for reliable basic functionality + - Advanced implementation (FLEXSEARCH_OVERLAY) available for future enhancements + +### Bug Fixes +- Fixed issue where search only worked on post content, not pages by modifying the `if post.is_post` condition in build_index() +- Added specific null checks in JavaScript (`if (searchButton)`, `if (searchInput)`, etc.) to prevent errors when elements aren't found +- Resolved event handler issues by moving key functions outside the DOMContentLoaded scope +- Fixed closeSearch function accessibility by defining it globally in the window scope +- Improved error handling with console.log statements for debugging common issues +- Changed URL path in fetch() to `/search_index.json` (with leading slash) to ensure correct file loading regardless of current page URL + +### Technical Changes +- Modified search index generation to remove the `post.is_post` filter that previously excluded pages from indexing +- Added support for tags in the search index: `item.meta('tags')` is now included in each indexed item +- Changed the search approach to concatenate multiple fields (`title + content + tags`) for more comprehensive search. This can be changed in `build_index` and in + ```javascript + // Change here which keys should be used for the search index. + searchIndex.add(key, data[key].title + " " + data[key].content + data[key].tags + " " + data[key].content); + ``` +- Implemented two distinct JavaScript implementations: + - The default simple version (FLEXSEARCH_EXTEND) prioritizes reliability + - An optional advanced version (FLEXSEARCH_OVERLAY) with separate title/content indices +- Changed index URL from relative to absolute path (`/search_index.json`) to avoid path resolution issues +- Added content type field to search index to distinguish between posts and pages +- Commented out content indexing in plugin code but added comprehensive content indexing in JavaScript + +### Documentation +- Added comprehensive documentation for new features +- Updated installation and configuration instructions +- Added code comments for better maintainability + +--- + +## v0.1 (Initial Release) +- Basic search functionality for posts +- Support for triggering search via button click or Enter key +- Simple search index generation +- Basic overlay and inline result display options \ No newline at end of file diff --git a/v8/flexsearch_plugin/README.md b/v8/flexsearch_plugin/README.md index 362cb648..669b44e7 100644 --- a/v8/flexsearch_plugin/README.md +++ b/v8/flexsearch_plugin/README.md @@ -1,244 +1,232 @@ # flexsearch_plugin -This plugin adds search functionality to a Nikola Site. +This plugin adds search functionality to a Nikola static site. It generates a JSON file with posts, pages, and their metadata, then uses [flexsearch](https://github.com/nextapps-de/flexsearch) for fast client-side search. -It generates a json with all the articles, slugs and titles and then uses [flexsearch](https://github.com/nextapps-de/flexsearch) to search. +## Updates -It supports searching clicking the search button or pressing enter. +You can get the last updates in my [blog](https://diegocarrasco.com/project-nikola-flexsearch-plugin), or regularly checking here. -The s`earch_index.json` is (re)generated on `nikola build` +### v0.2 -# How to use +- Check the CHANGELOG.md (new file in the repo) for a summary of the changes. +- NOTE: I hope I didn't forget to document anything. -There are 2 options: +### v0.1 -- Use a normal div and add the search results there. -- Use an overlay with the search results. +- Initial version. -Here is an example of the overlay: +## Features - +- Fast client-side searching with FlexSearch +- Configurable indexing of posts and/or pages +- Support for both overlay and inline search results display +- Displays content type (post/page) in search results +- Search across titles, content, and tags +- Keyboard navigation (ESC to close overlay, Enter to search) +- Analytics tracking via UTM parameters (just a `?utm_source=internal_search` appended to the url in the results) -For a live example check https://diegocarrasco.com +## Installation +To install the plugin, use the Nikola plugin installation command: -## Use a normal div and extend and populate it withthe results +```shell +nikola plugin -i flexsearch_plugin +``` -Append this to your `BODY_END` in `conf.py` +**IMPORTANT** +Version 0.2 has `FLEXSEARCH_INDEX_PAGES = False` by default to maintain the default search behaviour of the previous version. -```html - - +```python +# Content indexing options +FLEXSEARCH_INDEX_POSTS = True # Index posts (default: True) +FLEXSEARCH_INDEX_PAGES = False # Index pages (default: False) +FLEXSEARCH_INDEX_DRAFTS = False # Index draft content (default: False) ``` -then add this where you want the search to appear +There are two provided search implementations that you can use: -```html - - -
+1. **FLEXSEARCH_EXTEND**: A simpler implementation that adds search results to a div (default) +2. **FLEXSEARCH_OVERLAY**: A more advanced implementation with overlay display (the one I use in https://diegocarrasco.com) + +Add one of these to your `BODY_END` in `conf.py`: + +```python +# Add the search script to your BODY_END +BODY_END = BODY_END + FLEXSEARCH_EXTEND # Or use FLEXSEARCH_OVERLAY ``` +## How to Use -## Use an overlay for the results +There are 2 options for displaying search results: -This js allows to click the button or press enter to search +Here is an example of the overlay: -```html - - - +### Option 1: Inline Search Results + +Add this HTML where you want the search box to appear: + +```html + + + ``` -add this to your template where you want the search to appear +This will display search results directly in the `search_results` div. + +### Option 2: Overlay Search Results + +Add this HTML where you want the search box to appear: ```html -