rspress-plugin-typesense 0.0.1 → 0.0.2

package/dist/index.d.ts

@@ -1,12 +1,49 @@
-import type { RspressPlugin } from '@rspress/core';
+import type { RouteMeta, RspressPlugin } from '@rspress/core';
 import type { ConfigurationOptions } from 'typesense/lib/Typesense/Configuration';
-import type { CustomCollectionSettingsConfig } from './types.js';
+import type { CustomCollectionSettingsConfig, DocSearchRecord } from './types.js';
 import { getDefaultCollectionFields } from './typesenseHelper.js';
-export type { CustomCollectionSettings, CustomCollectionSettingsConfig, } from './types.js';
+export type { CustomCollectionSettings, CustomCollectionSettingsConfig, DocSearchRecord, } from './types.js';
 export { getDefaultCollectionFields };
+/**
+ * Options for the Typesense plugin.
+ *
+ * The server configuration requires an API key with **write permissions**,
+ * as the plugin creates and manages collections during indexing.
+ */
 export interface TypesensePluginOptions {
-    typesenseOptions: ConfigurationOptions;
+    /**
+     * Typesense server connection options.
+     * The API key must have write permissions to create and index collections.
+     */
+    serverConfig: ConfigurationOptions;
+    /**
+     * The base name of the Typesense collection.
+     * Note: The plugin creates dedicated localized collections (e.g., `my_docs_en`).
+     */
     collectionName: string;
+    /**
+     * Optional schema overrides. Can be a global settings object or a map keyed by language.
+     */
     customCollectionSettings?: CustomCollectionSettingsConfig;
+    /**
+     * Whether to index code blocks into Typesense.
+     * Defaults to `false` to avoid search noise and bloated index sizes.
+     */
+    indexCodeBlocks?: boolean;
+    /**
+     * Whether a failed indexing attempt should crash the build process.
+     * Defaults to `true`.
+     */
+    failOnIndexError?: boolean;
+    /**
+     * Whether to automatically filter search results by the active documentation version.
+     * Defaults to `true`.
+     */
+    versionedSearch?: boolean;
+    /**
+     * Hook to mutate or enrich the record before it gets indexed.
+     * Useful for attaching custom fields or tags.
+     */
+    transformRecord?: (record: DocSearchRecord, route: RouteMeta) => DocSearchRecord;
 }
 export declare function pluginTypesense(options: TypesensePluginOptions): RspressPlugin;

package/dist/index.js

@@ -2,6 +2,7 @@ import path from "path";
 import fs from "fs";
 import { TypesenseHelper, getDefaultCollectionFields } from "./typesenseHelper.js";
 import { IndexFromHtml } from "./indexFromHtml.js";
+import { ImportError } from "typesense/lib/Typesense/Errors";
 function pluginTypesense(options) {
     let generatedRoutes = [];
     return {
@@ -12,11 +13,20 @@ function pluginTypesense(options) {
         async routeGenerated (routes) {
             generatedRoutes = routes;
         },
+        async addRuntimeModules () {
+            const configPayload = {
+                collectionName: options.collectionName,
+                versionedSearch: options.versionedSearch ?? true
+            };
+            return {
+                'virtual-typesense-config': `export default ${JSON.stringify(configPayload)};`
+            };
+        },
         async afterBuild (config, isProd) {
             if (!isProd) return;
             const outDir = config.outDir || 'doc_build';
             const defaultLang = config.lang || 'en';
-            const isVersioned = config.search?.versioned ?? true;
+            const isVersioned = options.versionedSearch ?? true;
             const defaultVersion = config.multiVersion?.default || '';
             if (0 === generatedRoutes.length) return void console.warn(`\n\x1b[33m⚠ [TypesensePlugin] No routes generated.\x1b[0m \x1b[90mSkipping indexing.\x1b[0m\n`);
             const routeGroups = {};
@@ -37,7 +47,9 @@ function pluginTypesense(options) {
                 routeGroups[groupKey].routes.push(route);
             }
             if (0 === Object.keys(routeGroups).length) return void console.warn(`\n\x1b[33m⚠ [TypesensePlugin] No routes found for indexing.\x1b[0m \x1b[90mSkipping indexing process.\x1b[0m\n`);
-            const extractor = new IndexFromHtml();
+            const extractor = new IndexFromHtml({
+                indexCodeBlocks: options.indexCodeBlocks ?? false
+            });
             for(const groupKey in routeGroups){
                 const { locale, routes } = routeGroups[groupKey];
                 const aliasName = `${options.collectionName}_${locale}`;
@@ -47,15 +59,23 @@ function pluginTypesense(options) {
                 console.log(`\n\x1b[1m\x1b[36m[TypesensePlugin]\x1b[0m \x1b[1mProcessing group:\x1b[0m \x1b[35m${aliasName}\x1b[0m \x1b[90m(${routes.length} routes)\x1b[0m`);
                 const localizedCustomSettings = resolveCustomSettings(options.customCollectionSettings, locale);
                 const helper = new TypesenseHelper({
-                    config: options.typesenseOptions,
+                    config: options.serverConfig,
                     aliasName,
                     collectionNameTmp,
                     customSettings: localizedCustomSettings,
                     locale,
                     isVersioned
                 });
-                await helper.init();
-                await helper.createTmpCollection();
+                try {
+                    await helper.init();
+                    await helper.createTmpCollection();
+                } catch (error) {
+                    console.error(`\n\x1b[31m✖ [TypesensePlugin] Failed to initialize/create collection:\x1b[0m \x1b[37m${collectionNameTmp}\x1b[0m`);
+                    console.error(`  \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m\n`);
+                    if (false !== options.failOnIndexError) throw error;
+                    console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping group indexing due to failOnIndexError=false.\x1b[0m");
+                    continue;
+                }
                 let totalRecords = 0;
                 for (const route of routes){
                     const version = route.version || defaultVersion;
@@ -79,22 +99,30 @@ function pluginTypesense(options) {
                     }
                     try {
                         const htmlContent = fs.readFileSync(htmlPath, 'utf-8');
-                        const records = extractor.getRecords(htmlContent, route.routePath, locale);
+                        let records = extractor.getRecords(htmlContent, route.routePath, locale);
                         if (isVersioned && version) records.forEach((r)=>r.version = version);
+                        if (options.transformRecord) records = records.map((record)=>options.transformRecord(record, route));
                         if (records.length > 0) totalRecords += await helper.addRecords(records, route.routePath, false, padLength);
                     } catch (error) {
                         const fillerLength = Math.max(2, padLength - route.routePath.length);
                         const filler = '\x1b[90m' + '.'.repeat(fillerLength) + '\x1b[0m';
                         console.error(`  \x1b[31m✖\x1b[0m \x1b[37m${route.routePath}\x1b[0m ${filler} \x1b[31m failed\x1b[0m \x1b[90m(Processing error)\x1b[0m`);
-                        console.error(`    \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m`);
+                        if (error instanceof ImportError) {
+                            console.error("    \x1b[31m↳ Import error\x1b[0m");
+                            console.error(error.importResults);
+                            if (false !== options.failOnIndexError) throw error;
+                            console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping failure due to failOnIndexError=false.\x1b[0m");
+                        } else console.error(`    \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m`);
                     }
                 }
                 try {
                     await helper.commitTmpCollection();
                     console.log(`\x1b[32m✔ Indexing complete for\x1b[0m \x1b[35m${aliasName}\x1b[0m \x1b[90m—\x1b[0m \x1b[33m${totalRecords}\x1b[0m \x1b[90mtotal records!\x1b[0m`);
                 } catch (error) {
-                    console.error(`[TypesensePlugin] Failed to commit collection ${aliasName}:`, error);
-                    throw error;
+                    console.error(`\n\x1b[31m✖ [TypesensePlugin] Failed to commit collection:\x1b[0m \x1b[37m${aliasName}\x1b[0m`);
+                    console.error(`  \x1b[31m↳ ${error instanceof Error ? error.message : error}\x1b[0m\n`);
+                    if (false !== options.failOnIndexError) throw error;
+                    console.warn("\x1b[33m⚠ [TypesensePlugin] Skipping failure due to failOnIndexError=false.\x1b[0m");
                 }
             }
         }
@@ -102,7 +130,7 @@ function pluginTypesense(options) {
 }
 function resolveCustomSettings(settings, locale) {
     if (!settings) return null;
-    const isGlobalConfig = 'token_separators' in settings || 'symbols_to_index' in settings || 'field_definitions' in settings || 'enable_nested_fields' in settings;
+    const isGlobalConfig = 'token_separators' in settings || 'symbols_to_index' in settings || 'fields' in settings || 'enable_nested_fields' in settings;
     if (isGlobalConfig) return settings;
     const perLangSettings = settings;
     return perLangSettings[locale] || null;

package/dist/indexFromHtml.d.ts

@@ -2,6 +2,9 @@ import type { DocSearchRecord } from './types.js';
 export declare class IndexFromHtml {
     private levels;
     private selectors;
+    constructor(options?: {
+        indexCodeBlocks?: boolean;
+    });
     getRecords(html: string, url: string, lang?: string): DocSearchRecord[];
     private getLevelFromTag;
     private generateEmptyHierarchy;

package/dist/indexFromHtml.js

@@ -10,42 +10,50 @@ class IndexFromHtml {
         'lvl5',
         'lvl6'
     ];
-    selectors = {
-        lvl0: {
-            selector: '.rp-nav-menu__item--active',
-            global: true
-        },
-        lvl1: {
-            selector: '.rp-doc h1',
-            global: false
-        },
-        lvl2: {
-            selector: '.rp-doc h2',
-            global: false
-        },
-        lvl3: {
-            selector: '.rp-doc h3',
-            global: false
-        },
-        lvl4: {
-            selector: '.rp-doc h4',
-            global: false
-        },
-        lvl5: {
-            selector: '.rp-doc h5',
-            global: false
-        },
-        lvl6: {
-            selector: '.rp-doc h6',
-            global: false
-        },
-        content: {
-            selector: '.rp-doc p, .rp-doc li, .rp-doc table, .rp-doc .rp-callout, .rp-doc .rp-codeblock__content .rp-codeblock__content__scroll-container',
-            global: false
-        }
-    };
+    selectors;
+    constructor(options){
+        const docClass = '.rspress-doc';
+        let contentSelector = `${docClass} p, ${docClass} li, ${docClass} td, ${docClass} th`;
+        if (options?.indexCodeBlocks) contentSelector += `, ${docClass} pre > code`;
+        this.selectors = {
+            lvl0: {
+                selector: '.rp-nav-menu__item--active',
+                global: true
+            },
+            lvl1: {
+                selector: `${docClass} h1`,
+                global: false
+            },
+            lvl2: {
+                selector: `${docClass} h2`,
+                global: false
+            },
+            lvl3: {
+                selector: `${docClass} h3`,
+                global: false
+            },
+            lvl4: {
+                selector: `${docClass} h4`,
+                global: false
+            },
+            lvl5: {
+                selector: `${docClass} h5`,
+                global: false
+            },
+            lvl6: {
+                selector: `${docClass} h6`,
+                global: false
+            },
+            content: {
+                selector: contentSelector,
+                global: false
+            }
+        };
+    }
     getRecords(html, url, lang) {
         const $ = __rspack_external_cheerio.load(html);
+        $('.rp-badge').remove();
+        $('.rp-not-doc').remove();
         const records = [];
         const getGlobalText = (selector)=>{
             const el = $(selector).first();
@@ -92,7 +100,7 @@ class IndexFromHtml {
             let levelWeight;
             if ('content' !== currentLevel) levelWeight = 100 - 10 * currentLevelInt;
             else {
-                const isCodeBlock = el.hasClass('rp-codeblock__content__scroll-container') || el.parents('.rp-codeblock, pre').length > 0;
+                const isCodeBlock = 'code' === tagName || el.parents('pre').length > 0;
                 levelWeight = isCodeBlock ? 0 : 10;
             }
             const weight = {

package/dist/runtime/RealSearch.d.ts

@@ -1,10 +1,12 @@
 import type { DocSearchProps } from 'typesense-docsearch-react';
 import type { Locales } from './locales.js';
+export type TypesenseDocSearchProps = Omit<DocSearchProps, 'translations' | 'typesenseCollectionName' | 'typesenseSearchParameters'> & {
+    typesenseSearchParameters?: DocSearchProps['typesenseSearchParameters'];
+};
 type SearchProps = {
-    docSearchProps: Omit<DocSearchProps, 'translations'>;
+    docSearchProps: TypesenseDocSearchProps;
     locales?: Locales;
-    versionedSearch?: boolean;
 };
-declare function Search({ locales, versionedSearch, docSearchProps: { typesenseCollectionName, transformItems, typesenseSearchParameters, ...docSearchProps }, }: SearchProps): import("react/jsx-runtime").JSX.Element;
+declare function Search({ locales, docSearchProps: { transformItems, typesenseSearchParameters, ...docSearchProps }, }: SearchProps): import("react/jsx-runtime").JSX.Element;
 export type { SearchProps };
 export default Search;

package/dist/runtime/RealSearch.js

@@ -2,6 +2,7 @@ import { Fragment, jsx } from "react/jsx-runtime";
 import { DocSearch } from "typesense-docsearch-react";
 import { useLang, useNavigate, useVersion } from "@rspress/core/runtime";
 import { Link } from "@theme";
+import virtual_typesense_config from "virtual-typesense-config";
 const Hit = ({ hit, children })=>/*#__PURE__*/ jsx(Link, {
         href: hit.url,
         children: children
@@ -10,18 +11,18 @@ const safeEscapeHighlights = (str)=>{
     if (!str) return str;
     return str.replace(/<(?!mark>|\/mark>)/gi, '&lt;').replace(/(?<!<mark|<\/mark)>/gi, '&gt;');
 };
-function Search({ locales = {}, versionedSearch = true, docSearchProps: { typesenseCollectionName, transformItems, typesenseSearchParameters, ...docSearchProps } }) {
+function Search({ locales = {}, docSearchProps: { transformItems, typesenseSearchParameters, ...docSearchProps } }) {
     const navigate = useNavigate();
     const version = useVersion();
     const lang = useLang() || 'en';
     const { translations, placeholder } = locales?.[lang] ?? {};
-    const resolvedCollectionName = `${typesenseCollectionName}_${lang}`;
+    const resolvedCollectionName = `${virtual_typesense_config.collectionName}_${lang}`;
     const searchParams = {
         ...typesenseSearchParameters || {}
     };
     const filters = [];
     if (searchParams.filter_by) filters.push(`(${searchParams.filter_by})`);
-    if (versionedSearch && version) filters.push(`version:=\`${version}\``);
+    if (virtual_typesense_config.versionedSearch && version) filters.push(`version:=\`${version}\``);
     if (filters.length > 0) searchParams.filter_by = filters.join(' && ');
     return /*#__PURE__*/ jsx(Fragment, {
         children: /*#__PURE__*/ jsx(DocSearch, {

package/dist/runtime/index.d.ts

@@ -1,2 +1,3 @@
-export { type Locales, RU_LOCALES, ZH_LOCALES } from './locales.js';
+export { type Locales, RU_LOCALES, ZH_LOCALES, VN_LOCALES } from './locales.js';
 export { Search, type SearchProps } from './Search.js';
+export type { TypesenseDocSearchProps } from './RealSearch.js';

package/dist/runtime/index.js

@@ -1,2 +1,2 @@
-export { RU_LOCALES, ZH_LOCALES } from "./locales.js";
+export { RU_LOCALES, VN_LOCALES, ZH_LOCALES } from "./locales.js";
 export { Search } from "./Search.js";

package/dist/runtime/locales.d.ts

@@ -5,3 +5,4 @@ export type Locales = Record<string, {
 }>;
 export declare const ZH_LOCALES: Locales;
 export declare const RU_LOCALES: Locales;
+export declare const VN_LOCALES: Locales;

package/dist/runtime/locales.js

@@ -84,4 +84,47 @@ const RU_LOCALES = {
         }
     }
 };
-export { RU_LOCALES, ZH_LOCALES };
+const VN_LOCALES = {
+    vn: {
+        placeholder: 'Tìm kiếm tài liệu',
+        translations: {
+            button: {
+                buttonText: 'Tìm kiếm',
+                buttonAriaLabel: 'Tìm kiếm'
+            },
+            modal: {
+                searchBox: {
+                    resetButtonTitle: 'Xóa truy vấn',
+                    resetButtonAriaLabel: 'Xóa truy vấn',
+                    cancelButtonText: 'Hủy',
+                    cancelButtonAriaLabel: 'Hủy'
+                },
+                startScreen: {
+                    recentSearchesTitle: 'Gần đây',
+                    noRecentSearchesText: 'Chưa có tìm kiếm gần đây',
+                    saveRecentSearchButtonTitle: 'Lưu tìm kiếm này',
+                    removeRecentSearchButtonTitle: 'Xóa tìm kiếm này khỏi lịch sử',
+                    favoriteSearchesTitle: 'Yêu thích',
+                    removeFavoriteSearchButtonTitle: 'Xóa tìm kiếm này khỏi mục yêu thích'
+                },
+                errorScreen: {
+                    titleText: 'Không thể tải kết quả',
+                    helpText: 'Hãy kiểm tra lại kết nối mạng của bạn.'
+                },
+                footer: {
+                    selectText: 'để chọn',
+                    navigateText: 'để di chuyển',
+                    closeText: 'để đóng',
+                    searchByText: 'Vận hành bởi'
+                },
+                noResultsScreen: {
+                    noResultsText: 'Không có kết quả cho',
+                    suggestedQueryText: 'Hãy thử tìm với từ khóa',
+                    reportMissingResultsText: 'Bạn nghĩ truy vấn này nên có kết quả?',
+                    reportMissingResultsLinkText: 'Hãy cho chúng tôi biết.'
+                }
+            }
+        }
+    }
+};
+export { RU_LOCALES, VN_LOCALES, ZH_LOCALES };

package/dist/types.d.ts

@@ -1,3 +1,4 @@
+import { CollectionFieldSchema } from 'typesense/lib/Typesense/Collection';
 import type { CollectionCreateSchema } from 'typesense/lib/Typesense/Collections';
 export interface Hierarchy {
     [key: string]: string | null | undefined;
@@ -36,7 +37,8 @@ export interface FieldsParams {
 export interface CustomCollectionSettings {
     token_separators?: CollectionCreateSchema['token_separators'];
     symbols_to_index?: CollectionCreateSchema['symbols_to_index'];
-    fields?: (params: FieldsParams) => CollectionCreateSchema['fields'];
+    fields?: (params: FieldsParams) => CollectionFieldSchema[];
     enable_nested_fields?: CollectionCreateSchema['enable_nested_fields'];
 }
+/**  Allows a single global config OR a map of configs keyed by language (e.g. `{ en: {...}, zh: {...} }`) */
 export type CustomCollectionSettingsConfig = CustomCollectionSettings | Record<string, CustomCollectionSettings>;

package/dist/typesenseHelper.d.ts

@@ -1,6 +1,6 @@
-import type { CollectionCreateSchema } from 'typesense/lib/Typesense/Collections';
 import type { ConfigurationOptions } from 'typesense/lib/Typesense/Configuration';
 import type { DocSearchRecord, CustomCollectionSettings, FieldsParams } from './types.js';
+import { CollectionFieldSchema } from 'typesense/lib/Typesense/Collection';
 export interface TypesenseHelperOptions {
     config: ConfigurationOptions;
     aliasName: string;
@@ -47,4 +47,4 @@ export declare class TypesenseHelper {
  *   },
  * }
  */
-export declare function getDefaultCollectionFields({ locale, isVersioned, }: FieldsParams): CollectionCreateSchema['fields'];
+export declare function getDefaultCollectionFields({ locale, isVersioned, }: FieldsParams): CollectionFieldSchema[];

package/dist/typesenseHelper.js

@@ -107,7 +107,7 @@ class TypesenseHelper {
             if (record.hierarchy && null != record.hierarchy[lvlKey]) transformedRecord[`hierarchy.lvl${x}`] = record.hierarchy[lvlKey];
             if (record.hierarchy_radio && null != record.hierarchy_radio[lvlKey]) transformedRecord[`hierarchy_radio.lvl${x}`] = record.hierarchy_radio[lvlKey];
         }
-        if (isVersioned && record.version && 'string' == typeof record.version) transformedRecord['version'] = record.version.split(',');
+        if (isVersioned && record.version && 'string' == typeof record.version) transformedRecord['version'] = record.version;
         else if (!isVersioned) delete transformedRecord['version'];
         return transformedRecord;
     }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "rspress-plugin-typesense",
-  "description": "A plugin to add Typesense-powered search to your Rspress site",
-  "version": "0.0.1",
+  "description": "A plugin that adds lightning-fast, typo-tolerant, Typesense-powered search to your Rspress site",
+  "version": "0.0.2",
   "type": "module",
   "exports": {
     ".": {