Smart-search-plugin NPM

Smart Search Plugin for Docusaurus

A metadata-driven search plugin for Docusaurus 2.x that provides targeted, efficient search capabilities with an elegant, accessible interface. By leveraging metadata keywords, this plugin delivers precise search results while working seamlessly offline and in firewall-restricted environments.

👉 Try the live demo | 📝 Read the full blog post

Support for Docusaurus 3.x is a work in progress. Stay tuned!

Why Smart Search?

The Smart Search Plugin reintroduces the proven concept of metadata keywords for documentation search while adding modern fuzzy search capabilities:

🎯 Targeted Results: Content tagged with relevant metadata receives higher ranking
🔍 Fuzzy Search: Intelligent matching tolerates typos and partial matches
🏃‍♀️ Offline Operation: Works behind firewalls without external API dependencies
⚡️ Local Testing: Test search functionality during development
📱 Modern Interface: Responsive design with full keyboard navigation
♿️ Accessibility: ARIA-compliant with keyboard navigation and screen reader support

Installation

npm install smart-search-plugin

yarn add smart-search-plugin

Configuration

Add the plugin to your docusaurus.config.js:

const path = require('path');

  staticDirectories: ['static'], // Required for search index

  plugins: [
    path.resolve(__dirname, 'node_modules/smart-search-plugin')
  ],

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          routeBasePath: '/',  // Required
          path: 'docs', // Required for the correct linking of topics
          showLastUpdateTime: true, // Enables last update display
        },
      },
    ],
  ],

  themeConfig: {
       navbar: {
      items: [
        {
          type: 'search',
          position: 'right',
        },
      ],
    },
  },
};

Document structure

Required directory structure

your-docusaurus-site/
├── docs/                   # Documentation root
│   ├── intro.md           # Documentation files
│   └── advanced/
│       └── config.md
├── static/                 # Static assets directory
└── docusaurus.config.js    # Configuration file

Frontmatter configuration

Your markdown files can include these frontmatter fields for enhanced search functionality:

---
title: Document Title
description: A brief description that appears in search results
keywords: [search, docusaurus, plugin]
draft: false                # Exclude from search when true
last_update:               # Optional update tracking
  date: 2024-03-20
  author: John Doe
---

Content processing

Smart content indexing

The plugin processes your content with these features:

Intelligent caching
- File-based caching system for faster builds
- Automatic detection of content changes
- Incremental rebuilding for modified files only
Content normalization
- Consistent URL generation across platforms
- Special handling for index files
- Clean URL paths for improved SEO
Automatic exclusions Content automatically excluded from search: - Root/welcome page (URL: '/') - Draft documents - Content in excluded folders (default: 'contributor-guide') - Files with draft: true in frontmatter