@easyops-cn/docusaurus-search-local 0.51.1 → 0.52.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [0.52.0](https://github.com/easyops-cn/docusaurus-search-local/compare/v0.51.1...v0.52.0) (2025-07-16)
+
+
+### Features
+
+* Add configurable keyboard shortcut for search bar focus ([92b32ee](https://github.com/easyops-cn/docusaurus-search-local/commit/92b32ee0ba0ee63664b3ae2cae9aa92b433025cf)), closes [#516](https://github.com/easyops-cn/docusaurus-search-local/issues/516)
+
 ## [0.51.1](https://github.com/easyops-cn/docusaurus-search-local/compare/v0.51.0...v0.51.1) (2025-06-19)
 
 

package/dist/client/client/theme/SearchBar/SearchBar.jsx

@@ -9,10 +9,12 @@ import { useActivePlugin } from "@docusaurus/plugin-content-docs/client";
 import { fetchIndexesByWorker, searchByWorker } from "../searchByWorker";
 import { SuggestionTemplate } from "./SuggestionTemplate";
 import { EmptyTemplate } from "./EmptyTemplate";
-import { Mark, searchBarShortcut, searchBarShortcutHint, searchBarPosition, docsPluginIdForPreferredVersion, indexDocs, searchContextByPaths, hideSearchBarWithNoSearchContext, useAllContextsWithNoSearchContext, } from "../../utils/proxiedGenerated";
+import { Mark, searchBarShortcut, searchBarShortcutHint, searchBarShortcutKeymap, searchBarPosition, docsPluginIdForPreferredVersion, indexDocs, searchContextByPaths, hideSearchBarWithNoSearchContext, useAllContextsWithNoSearchContext, } from "../../utils/proxiedGenerated";
 import LoadingRing from "../LoadingRing/LoadingRing";
 import { normalizeContextByPath } from "../../utils/normalizeContextByPath";
 import { searchResultLimits } from "../../utils/proxiedGeneratedConstants";
+import { parseKeymap, matchesKeymap, getKeymapHints } from "../../utils/keymap";
+import { isMacPlatform } from "../../utils/platform";
 import styles from "./SearchBar.module.css";
 async function fetchAutoCompleteJS() {
     const autoCompleteModule = await import("@easyops-cn/autocomplete.js");
@@ -291,9 +293,7 @@ export default function SearchBar({ handleSearchBarToggle, }) {
         }
     }, []);
     // Implement hint icons for the search shortcuts on mac and the rest operating systems.
-    const isMac = isBrowser
-        ? /mac/i.test(navigator.userAgentData?.platform ?? navigator.platform)
-        : false;
+    const isMac = isBrowser ? isMacPlatform() : false;
     // Sync the input value and focus state for SSR
     useEffect(() => {
         const searchBar = searchBarRef.current;
@@ -312,13 +312,13 @@ export default function SearchBar({ handleSearchBarToggle, }) {
     // eslint-disable-next-line react-hooks/exhaustive-deps
     []);
     useEffect(() => {
-        if (!searchBarShortcut) {
+        if (!searchBarShortcut || !searchBarShortcutKeymap) {
             return;
         }
-        // Add shortcuts command/ctrl + K
+        const parsedKeymap = parseKeymap(searchBarShortcutKeymap);
+        // Add shortcuts based on custom keymap
         const handleShortcut = (event) => {
-            if ((isMac ? event.metaKey : event.ctrlKey) &&
-                (event.key === "k" || event.key === "K")) {
+            if (matchesKeymap(event, parsedKeymap)) {
                 event.preventDefault();
                 searchBarRef.current?.focus();
                 onInputFocus();
@@ -328,7 +328,7 @@ export default function SearchBar({ handleSearchBarToggle, }) {
         return () => {
             document.removeEventListener("keydown", handleShortcut);
         };
-    }, [isMac, onInputFocus]);
+    }, [onInputFocus, searchBarShortcutKeymap]);
     const onClearSearch = useCallback(() => {
         const params = new URLSearchParams(location.search);
         params.delete(SEARCH_PARAM_HIGHLIGHT);
@@ -359,9 +359,8 @@ export default function SearchBar({ handleSearchBarToggle, }) {
             searchBarShortcutHint &&
             (inputValue !== "" ? (<button className={styles.searchClearButton} onClick={onClearSearch}>
             ✕
-          </button>) : (isBrowser && (<div className={styles.searchHintContainer}>
-              <kbd className={styles.searchHint}>{isMac ? "⌘" : "ctrl"}</kbd>
-              <kbd className={styles.searchHint}>K</kbd>
+          </button>) : (isBrowser && searchBarShortcutKeymap && (<div className={styles.searchHintContainer}>
+              {getKeymapHints(searchBarShortcutKeymap, isMac).map((hint, index) => (<kbd key={index} className={styles.searchHint}>{hint}</kbd>))}
             </div>)))}
     </div>);
 }

package/dist/client/client/utils/keymap.js

@@ -0,0 +1,75 @@
+import { isMacPlatform } from './platform';
+export function parseKeymap(keymap) {
+    const parts = keymap.toLowerCase().split('+');
+    const result = {
+        key: '',
+        ctrl: false,
+        alt: false,
+        shift: false,
+        meta: false,
+    };
+    // Detect if we're on Mac to handle 'mod' appropriately
+    const isMac = isMacPlatform();
+    for (const part of parts) {
+        const trimmed = part.trim();
+        switch (trimmed) {
+            case 'ctrl':
+                result.ctrl = true;
+                break;
+            case 'cmd':
+                result.meta = true;
+                break;
+            case 'mod':
+                if (isMac) {
+                    result.meta = true;
+                }
+                else {
+                    result.ctrl = true;
+                }
+                break;
+            case 'alt':
+                result.alt = true;
+                break;
+            case 'shift':
+                result.shift = true;
+                break;
+            default:
+                result.key = trimmed;
+                break;
+        }
+    }
+    return result;
+}
+export function matchesKeymap(event, keymap) {
+    return (event.key.toLowerCase() === keymap.key &&
+        event.ctrlKey === keymap.ctrl &&
+        event.altKey === keymap.alt &&
+        event.shiftKey === keymap.shift &&
+        event.metaKey === keymap.meta);
+}
+export function getKeymapHints(keymap, isMac) {
+    const parsedKeymap = parseKeymap(keymap);
+    const hints = [];
+    // Handle original keymap string to detect 'mod' for proper hint display
+    const parts = keymap.toLowerCase().split('+').map(p => p.trim());
+    const hasMod = parts.includes('mod');
+    if (parsedKeymap.ctrl && !hasMod) {
+        hints.push('ctrl');
+    }
+    if (parsedKeymap.meta && !hasMod) {
+        hints.push(isMac ? '⌘' : 'cmd');
+    }
+    if (hasMod) {
+        hints.push(isMac ? '⌘' : 'ctrl');
+    }
+    if (parsedKeymap.alt) {
+        hints.push(isMac ? '⌥' : 'alt');
+    }
+    if (parsedKeymap.shift) {
+        hints.push(isMac ? '⇧' : 'shift');
+    }
+    if (parsedKeymap.key) {
+        hints.push(parsedKeymap.key.toUpperCase());
+    }
+    return hints;
+}

package/dist/client/client/utils/platform.js

@@ -0,0 +1,24 @@
+/**
+ * Detects if the current platform is macOS using modern, non-deprecated APIs.
+ * Falls back gracefully for older browsers or server-side rendering.
+ */
+export function isMacPlatform() {
+    // Handle server-side rendering or missing navigator
+    if (typeof navigator === 'undefined') {
+        return false;
+    }
+    // Try modern User-Agent Client Hints API first (if available)
+    if ('userAgentData' in navigator && navigator.userAgentData?.platform) {
+        const platform = navigator.userAgentData.platform.toLowerCase();
+        return platform.includes('mac');
+    }
+    // Fall back to user agent string parsing (more reliable than navigator.platform)
+    if (navigator.userAgent) {
+        return /mac/i.test(navigator.userAgent);
+    }
+    // Final fallback to deprecated navigator.platform for very old browsers
+    if (navigator.platform) {
+        return navigator.platform.toLowerCase().includes('mac');
+    }
+    return false;
+}

package/dist/server/server/utils/generate.js

@@ -6,7 +6,7 @@ const fs_1 = tslib_1.__importDefault(require("fs"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const getIndexHash_1 = require("./getIndexHash");
 function generate(config, dir) {
-    const { language, removeDefaultStopWordFilter, removeDefaultStemmer, highlightSearchTermsOnTargetPage, searchResultLimits, searchResultContextMaxLength, explicitSearchResultPath, searchBarShortcut, searchBarShortcutHint, searchBarPosition, docsPluginIdForPreferredVersion, indexDocs, searchContextByPaths, hideSearchBarWithNoSearchContext, useAllContextsWithNoSearchContext, fuzzyMatchingDistance, } = config;
+    const { language, removeDefaultStopWordFilter, removeDefaultStemmer, highlightSearchTermsOnTargetPage, searchResultLimits, searchResultContextMaxLength, explicitSearchResultPath, searchBarShortcut, searchBarShortcutHint, searchBarShortcutKeymap, searchBarPosition, docsPluginIdForPreferredVersion, indexDocs, searchContextByPaths, hideSearchBarWithNoSearchContext, useAllContextsWithNoSearchContext, fuzzyMatchingDistance, } = config;
     const indexHash = (0, getIndexHash_1.getIndexHash)(config);
     const contents = [];
     contents.push(`export const removeDefaultStemmer = ${JSON.stringify(removeDefaultStemmer)};`);
@@ -30,6 +30,7 @@ function generate(config, dir) {
     contents.push(`export const explicitSearchResultPath = ${JSON.stringify(explicitSearchResultPath)};`);
     contents.push(`export const searchBarShortcut = ${JSON.stringify(searchBarShortcut)};`);
     contents.push(`export const searchBarShortcutHint = ${JSON.stringify(searchBarShortcutHint)};`);
+    contents.push(`export const searchBarShortcutKeymap = ${JSON.stringify(searchBarShortcutKeymap)};`);
     contents.push(`export const searchBarPosition = ${JSON.stringify(searchBarPosition)};`);
     contents.push(`export const docsPluginIdForPreferredVersion = ${docsPluginIdForPreferredVersion === undefined
         ? "undefined"

package/dist/server/server/utils/validateOptions.js

@@ -27,6 +27,7 @@ const schema = utils_validation_1.Joi.object({
     ignoreCssSelectors: isStringOrArrayOfStrings.default([]),
     searchBarShortcut: utils_validation_1.Joi.boolean().default(true),
     searchBarShortcutHint: utils_validation_1.Joi.boolean().default(true),
+    searchBarShortcutKeymap: utils_validation_1.Joi.string().default("mod+k"),
     searchBarPosition: utils_validation_1.Joi.string().default("auto"),
     docsPluginIdForPreferredVersion: utils_validation_1.Joi.string(),
     zhUserDict: utils_validation_1.Joi.string(),

package/dist/types/index.d.ts

@@ -124,6 +124,17 @@ export interface PluginOptions {
      * @default true
      */
     searchBarShortcutHint?: boolean;
+    /**
+     * Custom keyboard shortcut to focus the search bar. Supports formats like:
+     * - "s" for single key
+     * - "ctrl+k" for key combinations
+     * - "cmd+k" for Command+K (Mac) / Ctrl+K (others)
+     * - "mod+k" for Command+K (Mac) / Ctrl+K (others) - recommended cross-platform option
+     * - "ctrl+shift+k" for multiple modifiers
+     *
+     * @default "mod+k"
+     */
+    searchBarShortcutKeymap?: string;
     /**
      * The side of the navbar the search bar should appear on. By default,
      * it will try to autodetect based on your docusaurus config according

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@easyops-cn/docusaurus-search-local",
-  "version": "0.51.1",
+  "version": "0.52.0",
   "description": "An offline/local search plugin for Docusaurus v3",
   "repository": {
     "type": "git",