Custom search sample or ability to reload search index help needed #2615

https://github.com/squidfunk/mkdocs-material/discussions/2615

Thermal-Shock on Apr 30, 2021 Hello my friends.

Our prebuilt mkdocs site is modified at runtime by javascript on a page-by-page basis to dynamically hide sections that are not applicable to a particular configuration. This is done simply by hiding various divs by class name. We also have a renumbering javascript which then runs on each page and renumbers the sections of any content left visible including their corresponding table of contents. This works in conjunction with a selection screen (a bunch of HTML selects) that rewrite the current URL history entry with these selection parameters, so when someone visits one of these pages, the aforementioned code knows what to hide and show.

This all works great, except for the site search of course, since it is not dynamic, and the search index would need to be categorised by all possible combinations, so not good. This is what I need help with.

Our current plan is at build time to walk all the combinations for pages that have dynamic content and generate a search_index_{section}_{combination}.json for each section and parameter combination. Later when someone makes a change on the selection screen we would like to construct a new search_index.json (in memory at least) by concatenating the correct json combinations we previously built, and then have the search work as normal on this new index.

Not being that familiar with the React way of coding, are there any samples which show calling out to get an index or build a search_index.json and return it such that the search framework reloads and uses it. All I can currently see is initialisation but no way to reload it or have it load my own json file or json from memory.

Any help getting this going would be immensely helpful. I’m a very experienced programmer, but just have very little react experience and this is also my first time trying to modify the mkdocs-material search integration.

Thank you! All the best.

Answered by squidfunk on Apr 30, 2021 As a start, the section on custom search explains how search works on a high level, but it’s more dedicated to users who want to replace the search engine without losing the interface. I believe that what you’re trying is certainly possible, but definitely tricky.

On a side note, Material for MkDocs is not a single page application, and thus not implemented on top of React. We use RxJS for all the plumbing, so a good understanding of that is definitely a plus when you want to dig into the internals. In general, the theme is very hackable and exposes a lot of what’s going on to hook into.

This folder includes the whole search implementation, i.e. all parts that are of interest, some of whi…

View full answer Replies:1 comment · 3 replies

squidfunk on Apr 30, 2021 Maintainer As a start, the section on custom search explains how search works on a high level, but it’s more dedicated to users who want to replace the search engine without losing the interface. I believe that what you’re trying is certainly possible, but definitely tricky.

This folder includes the whole search implementation, i.e. all parts that are of interest, some of which would need to be touched. I have a rough idea of how what you’re asking for could be pulled off, but I don’t have all of your specs available to sketch out a working solution. It’s a very specific request after all.

I’m available as a freelancer, so if you want professional support, just drop me an email.

3 replies @Thermal-Shock Thermal-Shock on May 1, 2021 Author Thanks you for the reply, your thoughts on what we are trying to do, and your clarification on your use of React. This was really helpful to me. Also thank you for offering your services. If we get in a jam, we may very well reach out to you for help.

We have already customised the search ourselves by adding additional meta tags to filter the search by. We also modified the worker to correct the location links that are returned based on the URL parameters, so have some level of comfort modifying this code, but are ideally just missing a modular way to override where the search_index.json itself comes from.

I can see the code to fetch the search_index.json in the initialise method, so one way would be for me to simply reload the page when our selection changes (and URL parameters). The page reload will cause the initialise to be called again, at which time I could read the URL parameters and construct/fetch the correct prebuilt search index based on them.

However I’d much prefer a way in which we can trigger a reload of the search index without having to reload the page. I’m sure this is trivial to someone who knows RxJS and this mkdocs-material repo, so if you can offer any help on this, it would be great.

All the best.

@squidfunk squidfunk on May 1, 2021 Maintainer However I’d much prefer a way in which we can trigger a reload of the search index without having to reload the page. I’m sure this is trivial to someone who knows RxJS and this mkdocs-material repo, so if you can offer any help on this, it would be great.

That’s the whole point – it’s not trivial. This is a use case we haven’t met before, and you’re already overwriting and extending specific parts of the theme. As I said, I have a rough idea, but there are definitely some parts of the source that would need to be touched, ergo, it’s possible but tricky, so nothing I can help you (or better: your company) with within my spare time 😉 Thus, it’s probably easiest if you go with the full page reload.

@Thermal-Shock Thermal-Shock on May 2, 2021 Author All fair points man. Thanks for the reply. In the end we are simply looking for a reinitialise function (thereby reloading the index). I could see this as a nice general enhancement to the library but as a professional developer myself, I respect your need for compensation. Let me see how we get on and I’ll reach out to you if we cannot write this ourselves and the page reload is not a good fit. All the best.

Answer selected by squidfunk