Support local search

[yanzhiwei147]

Is this a bug report?

NO

Have you read the [Contributing Guidelines on issues]

YES

Environment

None

Steps to Reproduce

None

Expected Behavior

None

Actual Behavior

None

Reproducible Demo

None

Request new feature

I have a website in my intranet, it generated use gitbook. Now i perfer to use the excellent website generator, and deprecated gitbook. But the tool miss local search capability while migrate process. So we have possible to provide local search(like hexo next theme)?

[cuongnv-ibl]

Do you mean Algoria Search locally ?

[ntlex]

In my company we are looking for a similar solution using Lunrjs, where you can simply index your article locally. At the moment it looks pretty impossible to workaround reactjs and extend the navigation bar to allow the search field to appear without an algolia setup.

[endiliey]

@ntlex Hmm, thats a good point. It is indeed not possible to extend the navigation bar to allow your own search field (if not algolia) to appear without submitting a PR to Docusaurus itself.

Things will change in Docusaurus v2 though 😊.

[ntlex]

@endiliey when is Docusaurus v2 coming ?

[JoelMarcey]

@ntlex Hi. We are in the planning stages now.

[altafakhai]

We have been evaluating a few tools to generate an internal help system in our company. The help system will be hosted behind the firewall and will not be exposed to public. To use the search feature, we need to have Algolia enabled, which wants the site to be public. Is there a way we can use the Search feature without Algolia? I really like Docusaurus and want to go ahead with it. However, the Search limitation is pulling us back. Will there be an immediate solution to this?

[JoelMarcey]

Hi @altafakhai - I think we just responded to your tweet as well. We do not have a simple mechanism to support search behind a firewall at this point. We are looking at options for v2. There is probably a way to embed a search feature on your custom pages, but that is not optimal, of course.

I believe that Algolia has an offline feature, but I have never used it and I don't think it would easily integrate in the current version of Docusaurus.

cc: @s-pace

[s-pace]

👋 @altafakhai

You can use DocSearch on your internal network if you run it on your own. You will need to create your own configuration and then run it. We do not feature login so far but we are PR welcome. It is based on top of scrapy

You can inspire the configuration from the Docusarus's one.

Happy to help if you need anything else.

[endiliey]

@s-pace I have a question.

If we run the scraper on our own, it will still push the the crawled results to the Algolia index (which is not our own network), and it's not "offline" search. Its just not requiring the website to be publicly accessible (as in to be crawled).

Is this correct ?

[s-pace]

@endiliey Indeed.

You can still use algolia offline but regarding the use-case, it is what we will recommend.

[yanzhiwei147]

Thank everyone provide so much suggests. Now i express my solution:

1. Generate the index.xml to root directory while build website.
2. Add search bar on website.
3. Search from index.xml when search bar text input or change.

Information for your reference.

[altafakhai]

Thanks for the help, @JoelMarcey @s-pace

I will try to work with DocSearch and see if we get the desired results. Will keep you all posted with the progress.

Eagerly waiting for v2. 😃

[JoelMarcey]

@sbansal3096 is planning to work on this either for v1 or v2.

@endiliey @yangshun - are we planning on offering a local search implementation for v2. Or just a pluggable infrastructure for search?

[endiliey]

Just pluggable search box. I think he can try it on v1, the main implementation part is on building the docs index.

[JoelMarcey]

I think he can try it on v1, the main implementation part is on building the docs index.

@endiliey Do you mean he should only index *.md files and not worry about trying to index React pages, etc? If so, I think that is ok. I think @sbansal3096 should use an off the shelf indexer like lunr.js and run with that.

[cryptoads]

Any update on this?

[pauljamescleary]

Any update? Currently looking at static site generators for documentation. Like most things about Docusaurus except for the search. This is a nice project :)

[the-darc]

I have the same issue here on a Internal project and solved it with a server side search using @weixsong/elasticlunr.js.

I would like to send a PR with this solution at some time. But Unfortunately I do not have time to do it right now. For now it is available in @the-darc/Docusaurus.

[cryptoads]

Just implemented your fix. Looks good!! Cheers.

[haslam22]

+1 Local search would be an amazing addition. My use case is that I'd like to use Docusaurus for documentation hosted on an intranet and I can't pass any information to a third-party.

[lashomb]

Same use case as @haslam22 for me.

[SmolinPavel]

Waiting for this feature to be implemented too!

[joetidee]

... it's like being handed the keys to a Porsche .... with no engine :(

[JohnSeals]

Any update on this? Or do I just have to build my own? :-)

Thanks!

[yangshun]

Just to set expectations, the Docusaurus core team won't be working on this anytime soon. Our priority is getting feature parity with Docusaurus v1.

[JohnSeals]

Thanks for the quick reply @yangshun! So if I need to get local search running now is there a path you recommend? There are several options listed above but none of them seem to be really ready for primetime.

[hatzopoulos]

@JohnSeals

For what it's worth I got @the-darc's fork working for me with some modifications and it didn't take very long.

https://github.com/facebook/docusaurus/issues/776#issuecomment-480805342

[JohnSeals]

@hatzopoulos I tried it here and got it working too. Thanks for the tip and thanks to @the-darc!

[cmfcmf]

I have created a plugin for Docusaurus v2.0.0-alpha.40 that enables local search using lunr.js. The source is at https://github.com/cmfcmf/docusaurus-search-local and you can try it live at https://cmfcmf.github.io/OpenWeatherMap-PHP-API.

If you have any feedback or issues, feel free to open an issue in my repository. Be aware that search only works in the production build of your documentation (this is due to current limitations of the v2 plugin lifecycle apis).

[tomrav]

I have created a plugin for Docusaurus v2.0.0-alpha.40 that enables local search using lunr.js. The source is at https://github.com/cmfcmf/docusaurus-search-local and you can try it live at https://cmfcmf.github.io/OpenWeatherMap-PHP-API. ...

@cmfcmf I just integrated your plugin to my v2 project, works out-of-the-box and as expected - AWESOME. Sadly it's on a closed system, so I can't show off.

Thank you for sharing!

[JoelMarcey]

I can't wait to try this out!

cc @yangshun @jordwalke

[rcline]

@cmfcmf You are my hero! I was just about to do this and found you had just posted this solution only an hour earlier!! ❤️

Tested it out and works great! 🎉

[jordwalke]

Very cool @tomrav

[lelouch77]

I created an offline search plugin that looks similar to algolia search using lunr.js Check it out .. https://github.com/lelouch77/docusaurus-lunr-search

Demo is available at https://lelouch77.github.io/docusaurus-lunr-search-demo/

[yanzhiwei147]

Great! @endiliey Can we merge it into v2.

[JoelMarcey]

@yanzhiwei147 Endi passed away last month 😔

@yangshun - is this something to be merged into v2?

[yangshun]

I don't think we'll make this a core of v2 especially since we don't own the code. It could be left as a community-supported plugin.

[maximousblk]

I don't think we'll make this a core of v2 especially since we don't own the code. It could be left as a community-supported plugin.

@yangshun What can be possible problems if you make this a core feature? And what code are you talking about, the plugin or lunrjs?

---

As an alternative to lunsjs, I would like to suggest FlexSearch. It's super fast, less resource hungry and requires no dependencies. This can be turned into a plugin similar to @lelouch77's solution.

---

problem with the local full text solutions is the the index directly from the source code. This this makes them index unnecessary objects like comments, URLs, code snippets, etc. which add to the final index and look bad when someone searches through that. Algolia on the other hand indexes directly from the final build which removes all the unwanted elements.

What I'm trying to say is, if you need a proper local search, you need to first filter out the unnecessary elements from the raw markdown and then index it.

If you can implement this solution as a core feature in V2, this can be a very strong consideration point when choosing a documentation builder. Currently Docusaurus is behind Vuepress (personal opinion) because Vuepress at least supports native header search assisted by tags.

---

If Docusaurus got a native full-text search feature, that would be the best thing that happened to documentations. just saying

[JoelMarcey]

cc @slorber

[yangshun]

since we don't own the code.

The fact that the plugin is built by the community. The scenario I'm afraid of here is that we require patches to the community plugin but the maintainer is no longer active, we would then have to fork the project in order to make updates to it. We might relax the stance here because we're using remark-admonitions now which likewise is built by the community.

If you can implement this solution as a core feature in V2, this can be a very strong consideration point when choosing a documentation builder.

What's wrong with using Algolia and why is there a need for local search? Is it because the docs are behind a VPN?

[maximousblk]

What's wrong with using Algolia

Nothing. Don't remove algolia. It's just that a local alternative would be super helpful.

why is there a need for local search?

For proprietary software documentation. The index is stored on the algolia servers which can be a problem if ever it gets breached, all the documentation will be public. Though that is a very narrow scenario.

Another case would be if the documentation is stored on a network totally cut off from the internet.

And it will help with PWAs as the index would be available offline.

This would also help beginners as docsearch denies indexing example projects. And not everyone publishes their test projects.

No other documentation builders have proper search other than the ones hosted on their servers. Docsify has a native search but it has the filtering problems I mentioned earlier.

I'm very new to programming in general so I don't really know about the problems that occur while maintaining such a project.

[cmfcmf]

What's wrong with using Algolia and why is there a need for local search? Is it because the docs are behind a VPN?

The reason why I didn't want to use Algolia was mainly to avoid having to read through their terms of service and privacy policy to figure out if and what data they collect from visitors of my website when I load their JavaScript SDK and connect to their servers.

As an alternative to lunsjs, I would like to suggest FlexSearch. It's super fast, less resource hungry and requires no dependencies. This can be turned into a plugin similar to @lelouch77's solution.

Thank you for bringing up FlexSearch! This is certainly an interesting alternative. I will see if using that instead of lunrjs would work for my plugin.

[danforbes]

Thanks to the comments on this issue, I have found many helpful links for local search with Docusaurus v2, but I am currently on v1 and curious if anyone can help me out there. Is anyone aware of any established patterns for using local search with Docusaurus v1?

[JoelMarcey]

@danforbes - just curious, is there anything technical stopping you from moving to v2?

[danforbes]

Just like general time commitments and stuff...this is something I would like to get taken care of in a week's time. Is migrating to v2 fairly straightforward? How much of an impact will it have on the look-and-feel of our site?

[s-pace]

It is pretty quick and easy yes https://v2.docusaurus.io/docs/migrating-from-v1-to-v2/

[s-pace]

Impact is neat with the new features such as dark mode and interactive code snippet

[s-pace]

And you will soon have a new search UX like on https://docsearch.algolia.com/

[JoelMarcey]

@danforbes Yes, depending on the features your v1 site uses, it could be a straightforward conversion. We may have folks who might be able to help convert if you would like a pull request on it.

[danforbes]

Thank you guys I am going to take a look on my end :pray: