Add site search to the new MDX website

ChristianMurphy commented 2 years ago

Subject of the feature

Have a way to search all documentation pages on the website.

Problem

Currently there is no way to search for specific content on the MDX site itself. Adopters either have to click through pages looking for where a relevant section is, or to go off the website to a search engine and do a site scoped search from there. For example if I'm looking for the Vue guide, I have go click through the site until I eventually find https://v2.mdxjs.com/packages/vue/#use several layers of navigation in.

Expected behavior

Have a way to search the documentation built into the site

Alternatives

Don't include search on the site
Add a link to a search engine with the site scope setup

Potential solutions

https://www.algolia.com/for-open-source
https://programmablesearchengine.google.com
https://ddg.patdryburgh.com
(many others, most search engines provide an embed-able site search)

wooorm commented 2 years ago

Algolia was used in the v1 site: https://github.com/mdx-js/mdx/blob/master/packages/gatsby-theme-mdx/src/components/search.js.

mizozobu commented 2 years ago

This is probably the easiest way to integrate algolia to an OSS documentation site and probably this project can be listed on docsearch's homepage.

https://docsearch.algolia.com

shortcuts commented 1 year ago

Hey there! I can confirm DocSearch was running for the v1 website, and we still have the setup up and running!

I've made a (really basic) update on our side just to make it work for the current website, csb - live demo

You can use the credentials you see on the sandbox, they are yours and public so no worry about disclosing it. For the account owner, I see @johno so let me know if I should send a new invite or add someone else :)

wooorm commented 1 week ago

Done!

@shortcuts appreciate you looking in.

I believe I do not have access to algolia. John isn’t really active here anymore. Could you add me? Thanks!

wooorm commented 1 week ago

Oh, and two things, for you as a maintainer of these libraries:

the types seem wrong for the ESM build: https://github.com/mdx-js/mdx/blob/3f8344b3a21425a6ebd908599d88b0b6a5bbdb79/docs/_asset/index.js#L151.

recommend building with exactOptionalPropertyTypes: true, so that tools like ours which also do that, build okay:

node_modules/@algolia/autocomplete-shared/dist/esm/core/AutocompleteSource.d.ts:1:15 - error TS2724: '"@algolia/client-search"' has no exported member named 'FacetHit'. Did you mean 'FacetHits'?

1 import type { FacetHit, Hit } from '@algolia/client-search';
              ~~~~~~~~

node_modules/@algolia/autocomplete-shared/dist/esm/js/AutocompleteOptions.d.ts:23:18 - error TS2430: Interface 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/js/AutocompleteOptions").AutocompleteOptions<TItem>' incorrectly extends interface 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/core/AutocompleteOptions").AutocompleteOptions<TItem>'.
Types of property 'plugins' are incompatible.
  Type 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/js/AutocompletePlugin").AutocompletePlugin<any, any>[]' is not assignable to type 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/core/AutocompletePlugin").AutocompletePlugin<any, any>[]'.
    Type 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/js/AutocompletePlugin").AutocompletePlugin<any, any>' is not assignable to type 'import("/Users/tilde/Projects/oss/mdx/node_modules/@algolia/autocomplete-shared/dist/esm/core/AutocompletePlugin").AutocompletePlugin<any, any>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
      Type 'AutocompletePlugin<any, any>' is not assignable to type 'Partial<Pick<AutocompleteOptions<any>, "onStateChange" | "onSubmit" | "onReset"> & Pick<AutocompleteOptions<any>, "getSources">>' with 'exactOptionalPropertyTypes: true'. Consider adding 'undefined' to the types of the target's properties.
        Types of property 'getSources' are incompatible.
          Type 'GetSources<any> | undefined' is not assignable to type 'GetSources<any>'.
            Type 'undefined' is not assignable to type 'GetSources<any>'.

23 export interface AutocompleteOptions<TItem extends BaseItem> extends AutocompleteCoreOptions<TItem>, Partial<AutocompletePropGetters<TItem>> {
                  ~~~~~~~~~~~~~~~~~~~

node_modules/@docsearch/react/dist/esm/index.d.ts:2:10 - error TS2305: Module '"@algolia/client-search"' has no exported member 'SearchOptions'.

2 import { SearchOptions } from '@algolia/client-search';

mdx-js / mdx