[Feature request] Support self-hosted Typesense server for plugin-docsearch

[ricoapon]

Clear and concise description of the problem

I am working in a company that has documentation that is private (intellectual property). I have setup a Typesense server with a crawler for the documentation, but I am not able to configure the plugin-docsearch to use my own Typesense server.

Suggested solution

Allow "transformSearchClient" to be part of the docsearch configuration. This way, you could customize the object by installing the typesense npm package and applying it like this:

  plugins: {
    docsearch: {
      transformSearchClient: (searchClient) => {
        // Replace the default search client with your custom Typesense client
        return new TypesenseClient({
          nodes: [
            {
              host: 'your-typesense-server-url', // Your self-hosted Typesense server address
              port: 443, // or your specific port number
              protocol: 'https', // Use 'http' or 'https' based on your server setup
            },
          ],
          apiKey: 'your-typesense-search-only-api-key',
          connectionTimeoutSeconds: 2,
        });
      }
    },

Alternative

We can make the URLs configurable, making it possible to configure your own. This is a bigger overhaul for a feature that is (probably) not so populair. A "workaround" kind of solution would be good enough.

Additional context

Docusaurus does support this: (https://docusaurus.io/docs/search#using-typesense-docsearch).

[Mister-Hope]

I prefer this is a type issue, It seems that our code is not dropping this config.

[ricoapon]

@Mister-Hope

our code is not dropping this config

I am asking if this configuration could be added, not dropped. I don't get what you are trying to say.

I prefer this is a type issue

I don't see any documentation that this should be supported. Looking at the code, it seems like a very concious choice to not support this. Also, if this gets added, I am a big fan of adding the exact configuration in the documentation as well. This makes it obvious that it is supported. So I really do think it is a feature.

Feature or issue, I don't really care. We need to make some changes to get this to work :)

[Mister-Hope]

I am asking if this configuration could be added, not dropped. I don't get what you are trying to say.

Again, I think our code is natively supporting this, and I wonder if you have tried defineDocsearchConfig before opening this issue.

I prefer this is a type issue, It seems that our code is not dropping this config.

What I am talking is: I think we only need to fix the types. I never use transformSearchClient before and I actually do not want to try this config, so I need your feedback.

I am a big fan of adding the exact configuration in the documentation as well.

https://ecosystem.vuejs.press/plugins/search/docsearch.html#client-options

I don't think we need to provide any detailed description about docsearch options, you should look at it's own docs. To make it work with vuepress, we are hajacking some tranform options to ensure it can generate correct link and correct click/enter-key-down behvaiors, these shall not be displayed to normal users, while advanced users can read the code to find out how the built-in adjustment works.

[ricoapon]

I don't think we need to provide any detailed description about docsearch options, you should look at it's own docs

I have! And as it states directly in the docs you provided:

Omit<
  DocSearchProps,
  'hitComponent' | 'navigator' | 'transformSearchClient'
>

It explicitely says that transformSearchClient is not allowed in these properties. I have looked at the docsearch options, and to make it work that seems to be the only option.

Again, I think our code is natively supporting this, and I wonder if you have tried defineDocsearchConfig before opening this issue.

Then maybe I have missed something. Can you show me how to do this? I couldn't figure it out :(

[Mister-Hope]

What I want to say is that we are providing a incorrect client option that drop the option you need, this option can not be set in node side, but should work in browser.

So you should just set it in defineDocsearchConfig directly and omit the type warnings and see if everything works well, if so one of us can send a pr to fix the types, that's it.

[Mister-Hope]

See? Your option have higher prority than the built-in settings

[ricoapon]

Ahhh I get what you mean! Not sure how I can ignore the typescript compile errors, but there should be some way.

I still disagree with it being type issue, but if thats what you want I am fine with it!

[meteorlxy]

@ricoapon

It explicitely says that transformSearchClient is not allowed in these properties.

The Omit type was written by us, because if users set those options without adding necessary code, our built-in behaviors might be broken. Technically it is not "disallowed". It is only "discouraged" for common users.

We thought most users should not need those options, so we exclude them from the typing. But in fact you can still set them regardless of the typing.

Thus IMO it's at least a typing issue. Furthermore we can consider expose some built-in utils for advanced usage.

[ricoapon]

I have tried for 6 hours, and I could not get it to work. It is probably a skill issue. This is also unrelated to the plugin. I can easily get the transformSearchClient to work. I created a client.ts and called defineDocsearchConfig with the required parameters.

The thing is, I don't know what kind of client to return. I need some kind of adapter between docsearch and typesense, but I cannot it to work with any of the existing libraries. I would expect that typesense has some kind of adapter (they do), but I just don't know how to apply it in the code.

I think it is correct to say that this plugin has no bugs. I think it is not meant to connect to the typesense API, so it is up to the user to configure this. I think we can close this issue. Do you agree?

I would expect there to be Typesense documentation to get it to work, so I reported typesense/typesense-website#255 for this. If you guys have any idea how to make this work (see details in that issue), that would be very much appreciated!