Troubleshooting

Last updated on Dec 12, 2024

Open a doc issue   |   Edit this page

This guide helps you diagnose and resolve common issues with the Smart Search Plugin.

Search icon not appearing

Symptoms

• Search icon missing from navigation bar
• Navigation bar appears normal otherwise

Possible causes

1. Incorrect navbar configuration
2. Plugin not properly installed
3. Theme configuration issues

Solution

1. Check configuration file

   // docusaurus.config.js
   module.exports = {
     themeConfig: {
       navbar: {
         items: [
           {
             type: 'search',
             position: 'right',
           },
         ],
       },
     },
   };

2. Verify installation

   # Check package.json dependencies
   npm ls smart-search-plugin
   
   # Reinstall if necessary
   npm install smart-search-plugin

3. Clear cache and rebuild your project

   npm run clear
   npm run build

Search results not appearing

Symptoms

• Search bar works but shows no results
• No error messages in console

Possible causes

1. Missing document metadata
2. Incorrect file structure
3. Search index not generated

Solution

1. Verify document metadata

   ---
   title: Document Title
   description: Description text
   keywords: [keyword1, keyword2]
   ---

2. Check file structure

   docs/
   ├── intro.md
   └── category/
       └── document.md

3. Rebuild search index

   # Remove existing index
   rm -rf static/searchIndex.json
   
   # Rebuild project
   npm run build

Search performance issues

Symptoms

• Slow search response
• Browser performance degradation
• High memory usage

Solution

1. Optimize your metadata:

   • Reduce the number of keywords
   • Keep descriptions concise.
   • Remove unused metadata.

2. Check the size of the searchIndex.json file.

   // Check index file size
   ls -lh static/searchIndex.json

3. Optimize the performance.

   // docusaurus.config.js
   module.exports = {
     plugins: [
       [
         'smart-search-plugin',
         {
           maxResults: 8, // Limit results
           minQueryLength: 3, // Minimum search length
         },
       ],
     ],
   };

Console errors

• "Cannot find module 'smart-search-plugin'"

  # Solution
  npm install smart-search-plugin --save
• "Search index not found"

  # Solution
  npm run build

Reporting issues

When you encounter issues that aren't covered in the troubleshooting guide, here's how to get help.

1. Open a bug-report in the repo.

2. Provide a descriptive title, detailed description of the issue, and the following information:

   **Environment**
   
   - Plugin Version: [version]
   - Docusaurus Version: [version]
   - Node Version: [version]
   - OS: [operating system]
   
   **Steps to reproduce**
   
   1. [First Step]
   2. [Second Step]
   3. [Additional Steps...]
   
   **Expected behavior**
   
   [What you expected to happen]
   
   **Actual behavior**
   
   [What actually happened]
   
   **Additional context**
   
   [Any other relevant information]

3. Include your Docusaurus configuration.

   // docusaurus.config.js
   module.exports = {
     // Your configuration
   };

4. Add any error logs.

   # Build logs
   npm run build -- --debug