docs: add search (Algolia DocSearch)

[justinmk]

• apply for https://docsearch.algolia.com/
• implement the tips at https://docsearch.algolia.com/docs/tips/
  • 🚫 sitemap.xml (also apparently helps with SEO)... can be generated by gen_help_html.lua
    • Not needed: sitemap.xml ... will make the indexing faster, but will also give you more control over which page you'd like to include or not.
  • structured documentation ... we read the <h1>, ..., <h6> headings of your page to guess the hierarchy.
  • Add anchors to headings
• add search widget to https://neovim.io/doc/user
• add required css classes : https://docsearch.algolia.com/docs/required-configuration/#use-the-right-classes-as-recordprops
  • DocSearch-content
  • Every textual element (recordProps content) must be wrapped in a <p> or <li> tag. This content must be atomic and split into small entities.

Alternatives

if Algolia doesn't work for some reason...

• https://pagefind.app/

[shortcuts]

great idea :) let me know if you need help implementing it!

[shortcuts]

Hey @justinmk, I was browsing the docs today and saw some potential improvements of the crawler config, here's an example of some changes I've made https://crvdgc.csb.app/

If you like it let me know, I could update the config for the nvim crawler :D

[justinmk]

@shortcuts absolutely, can you share the config changes here? First thing I noticed is that the search results doesn't have that weird space.

neovim.io (has a weird space):

your site:

[shortcuts]

absolutely, can you share the config changes here?

Sure, I only changed the recordProps but there could still be improvements made especially if we want to highlight some parts of the docs with pageRank

          recordProps: {
            lvl0: {
              selectors: [
                "header h1",
                "article h1",
                "main h1",
                "h1",
                "head > title",
              ],
              defaultValue: "Documentation",
            },
            lvl1: ["article h2", "main h2", "h2"],
            lvl2: ["article h3", "main h3", "h3"],
            lvl3: ["article h4", "main h4", "h4"],
            lvl4: ["article h5", "main h5", "h5"],
            lvl5: ["article h6", "main h6", "h6"],
            content: [".help-tag", ".help-tag-right"],
          },

First thing I noticed is that the search results doesn't have that weird space.

I guess there might be some theming overlap with your CSS, looking at the code I can see that bootstrap apply some padding over the mark element, which might cause these small spaces

[shortcuts]

hey @justinmk, I have a bit of time this weekend if you want I can provide a PR to fix the DocSearch style along with updating the config on the Algolia side

[justinmk]

@shortcuts yes, style updates are very appreciated whenever you get a chance.

along with updating the config on the Algolia side

If you have other config hints to share please do, though I guess that can't be done as a PR.

[shortcuts]

@shortcuts yes, style updates are very appreciated whenever you get a chance.

sure, will take a look :)

If you have other config hints to share please do, though I guess that can't be done as a PR.

I don't have other hints for now but as I'm a DocSearch maintainer and I work on the Crawler at Algolia, I can update the config from there if you don't have time to do it

[justinmk]

I'm a DocSearch maintainer and I work on the Crawler at Algolia, I can update the config from there if you don't have time to do it

Interesting... 😆 yes, that would be great! The "diff" of changes would be nice to see here, for reference.

[shortcuts]

The "diff" of changes would be nice to see here, for reference.

Here's a screenshot of the diff from the Crawler UI directly, and the textual one in case you want to manually revert it. I applied the change but did not ran it yet in case you wanted to do it yourself or wait for the next schedule to kick in.

- recordProps: {
-   lvl0: {
-     selectors: "",
-     defaultValue: "Documentation",
-   },
-   lvl1: ["header h1", "article h1", "main h1", "h1", "head > title"],
-   lvl2: ["article h2", "main h2", "h2"],
-   lvl3: ["article h3", "main h3", "h3"],
-   lvl4: ["article h4", "main h4", "h4"],
-   lvl5: ["article h5", "main h5", "h5"],
-   lvl6: ["article h6", "main h6", "h6"],
-   //content: ["div.old-help-para", "div.help-para"],
-   content: [".help-tag", ".help-tag-right"],
- },
+ recordProps: {
+   lvl0: {
+     selectors: [
+       "header h1",
+       "article h1",
+       "main h1",
+       "h1",
+       "head > title",
+     ],
+     defaultValue: "Documentation",
+   },
+   lvl1: ["article h2", "main h2", "h2"],
+   lvl2: ["article h3", "main h3", "h3"],
+   lvl3: ["article h4", "main h4", "h4"],
+   lvl4: ["article h5", "main h5", "h5"],
+   lvl5: ["article h6", "main h6", "h6"],
+   //content: ["div.old-help-para", "div.help-para"],
+   content: [".help-tag", ".help-tag-right"],
+ },

---

I'll take a look at the rendering issue :)

[justinmk]

Nice, looks good! I see that I had lvl1 messed up.