• Stars
    star
    350
  • Rank 121,229 (Top 3 %)
  • Language
    JavaScript
  • License
    MIT License
  • Created almost 5 years ago
  • Updated over 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Offline / Local Search for Docusaurus v2. Try it live at:

Offline / Local Search for Docusaurus v2+

Version License code style: prettier GitHub issues GitHub last commit

Offline / local search for Docusaurus v2+ that works behind your firewall.

Feature Highlights:

  • Supports multiple documentation versions
  • Supports documentation written in languages other than English
  • Highlights search results
  • Customized parsers for docs, blogs, and general pages
  • Lazy-loads the index

Search in Action

Note: We use the open source algolia/autocomplete library for the searchbox. This library is just used as the frontend, and, unlike the default Docusaurus search experience (algolia/docsearch), does not connect to any Algolia or third-party servers.

Installation

npm install @cmfcmf/docusaurus-search-local

or

yarn add @cmfcmf/docusaurus-search-local

Usage

Add this plugin to the plugins array in docusaurus.config.js.

module.exports = {
  // ...
  plugins: [require.resolve("@cmfcmf/docusaurus-search-local")],

  // or, if you want to specify options:

  // ...
  plugins: [
    [
      require.resolve("@cmfcmf/docusaurus-search-local"),
      {
        // Options here
      },
    ],
  ],
};

The following options are available (defaults are shown below):

{
  // whether to index docs pages
  indexDocs: true,

  // Whether to also index the titles of the parent categories in the sidebar of a doc page.
  // 0 disables this feature.
  // 1 indexes the direct parent category in the sidebar of a doc page
  // 2 indexes up to two nested parent categories of a doc page
  // 3...
  //
  // Do _not_ use Infinity, the value must be a JSON-serializable integer.
  indexDocSidebarParentCategories: 0,

  // whether to index blog pages
  indexBlog: true,

  // whether to index static pages
  // /404.html is never indexed
  indexPages: false,

  // language of your documentation, see next section
  language: "en",

  // setting this to "none" will prevent the default CSS to be included. The default CSS
  // comes from autocomplete-theme-classic, which you can read more about here:
  // https://www.algolia.com/doc/ui-libraries/autocomplete/api-reference/autocomplete-theme-classic/
  // When you want to overwrite CSS variables defined by the default theme, make sure to suffix your
  // overwrites with `!important`, because they might otherwise not be applied as expected. See the
  // following comment for more information: https://github.com/cmfcmf/docusaurus-search-local/issues/107#issuecomment-1119831938.
  style: undefined,

  // The maximum number of search results shown to the user. This does _not_ affect performance of
  // searches, but simply does not display additional search results that have been found.
  maxSearchResults: 8,

  // lunr.js-specific settings
  lunr: {
    // When indexing your documents, their content is split into "tokens".
    // Text entered into the search box is also tokenized.
    // This setting configures the separator used to determine where to split the text into tokens.
    // By default, it splits the text at whitespace and dashes.
    //
    // Note: Does not work for "ja" and "th" languages, since these use a different tokenizer.
    tokenizerSeparator: /[\s\-]+/,
    // https://lunrjs.com/guides/customising.html#similarity-tuning
    //
    // This parameter controls the importance given to the length of a document and its fields. This
    // value must be between 0 and 1, and by default it has a value of 0.75. Reducing this value
    // reduces the effect of different length documents on a termโ€™s importance to that document.
    b: 0.75,
    // This controls how quickly the boost given by a common word reaches saturation. Increasing it
    // will slow down the rate of saturation and lower values result in quicker saturation. The
    // default value is 1.2. If the collection of documents being indexed have high occurrences
    // of words that are not covered by a stop word filter, these words can quickly dominate any
    // similarity calculation. In these cases, this value can be reduced to get more balanced results.
    k1: 1.2,
    // By default, we rank pages where the search term appears in the title higher than pages where
    // the search term appears in just the text. This is done by "boosting" title matches with a
    // higher value than content matches. The concrete boosting behavior can be controlled by changing
    // the following settings.
    titleBoost: 5,
    contentBoost: 1,
    tagsBoost: 3,
    parentCategoriesBoost: 2, // Only used when indexDocSidebarParentCategories > 0
  }
}

You can now use the search bar to search your documentation.

Important: Search only works for the statically built documentation (i.e., after you ran npm run docusaurus build in your documentation folder).

Search does not work in development (i.e., when running npm run docusaurus start). If you want to test search locally, first build the documentation with npm run docusaurus build, and then serve it via npm run docusaurus serve.

Non-English Documentation

Use the language option if your documentation is not written in English. You can either specify a single language or an array of multiple languages. The following languages are available:

ar, da, de, en, es, fi, fr, hi, hu, it, ja, nl, no, pt, ro, ru, sv, th, tr, vi, zh

Important: For Chinese language support (zh), you also have to install the nodejieba npm package at ^2.5.0.

Documentation Versions

Documentation versions created with the official Docusaurus docs plugin are supported. The search bar defaults to the latest version (not next, but the latest version defined in versions.json) when not on a documentation page (e.g., when looking at a blog post or a static page). If the user visits a documentation page, the version is extracted from the page and search will only search the documentation of that version. The searchbar placeholder text always reflects the currently detected documentation version.

Internationalization

This plugin supports documentation using Docusaurus i18n out of the box.. Please contribute additional translations by creating a new translation file in the codeTranslations subfolder and submitting a PR.

You can also adjust translations by modifiying the translations in <yourfolder>/i18n/<locale>/code.json that start with cmfcmf/d-s-l.. Read more at: https://docusaurus.io/docs/i18n/tutorial#translate-json-files

Debugging

If building your documentation produces an error, you can build it in debug mode to figure out which page is causing it. To do so, simply set the DEBUG environment variable when building your documentation: DEBUG=1 npm run docusaurus build.

CONTRIBUTING

Please see the CONTRIBUTING.md file for further information.

License

MIT

More Repositories

1

OpenWeatherMap-PHP-API

A PHP API to parse weather data and weather history from OpenWeatherMap.org.
PHP
323
star
2

Anno2018

Rewriting Anno 1602 from scratch by using extracted assets from the original game.
TypeScript
81
star
3

ic-pinout-diagram-generator

Generate beautiful pinout diagrams for integrated circuits.
TypeScript
49
star
4

MagicMouse

A webbrowser for Squeak using Chrome/Chromium. Not to be confused with a highly innovative pointing device.
Smalltalk
24
star
5

Anno2018-godot

Rewriting Anno 1602 from scratch, using extracted assets from the original game.
GDScript
8
star
6

TcpdfPlugin

This plugin is not maintained nor updated anymore. Please use the PDFModule as well as the PDFTheme instead!
PHP
7
star
7

snapcast-control

A simple web interface to control Snapcast, including limited support for Mopidy.
TypeScript
6
star
8

ReactS

React.js implemented in Squeak/Smalltalk
Smalltalk
6
star
9

SAP-HANA-Scala

Scala + SAP Hana University Project
CSS
5
star
10

rp2040-ws2811-client

A proof of concept of a WS2811/WS2812/WS2812B implementation on a RP2040 microcontroller
C++
4
star
11

OAuthModule

An OAuth implementation for Zikula. "Login with Google!"
PHP
4
star
12

notion-addon

An Unofficial Notion Addon for Gmail, Google Calendar and Google Drive
JavaScript
4
star
13

SeriousTheme

A blue theme for Zikula
JavaScript
3
star
14

ColumnWidthCalculator

Calculate "perfect" table column widths in PHP
PHP
3
star
15

SimpleTheme

A simple Zikula theme
JavaScript
3
star
16

PDFTheme

PDFTheme to be used with the PDFModule.
PHP
2
star
17

RoboRally

The board game RoboRally played by Lego NXTs
HTML
2
star
18

TicketManager

Zikula 1.3.x module
PHP
2
star
19

VolumeKnob

C++
1
star
20

ReentrantSimulator

A reentrant simulator for Squeak/Smalltalk.
Smalltalk
1
star
21

RSABundle

A Symfony demo bundle encrypting and decrypting RSA (german only)
PHP
1
star
22

embedded-nodejs-example

C++
1
star
23

Buzzer

Code for the buzzer used at @fsr-de.
C++
1
star
24

SqueakUtils

Some small utilities I use in my Squeak image
Smalltalk
1
star
25

vhdl-demo

A simple text editor written in VHDL for the Nexys 4 DDR Evaluation board.
VHDL
1
star
26

com_zikulaauth

Experimental integration between Joomla and Zikula
PHP
1
star
27

cmfcmf

1
star
28

Schattenbahnhof-Steuerung

Eine automatische Schattenbahnhofsteuerung fรผr die Modellbahn, auf Basis eines AtMega8 Mikroprozessors.
C
1
star
29

EventManagerTheme

A Zikula Theme based on Google Material Design and Bootstrap, designed for the EventManager module. It is not intended to be used on other sites.
JavaScript
1
star