gitbookio / plugin-algolia Goto Github PK

Here is Algolia's recommendations for the plugin:

As far as the Algolia plugin, here are my high-level recommendations:

• Reduce record size to improve performance (by splitting sections, paragraphs, etc). I noticed some big records for larger books, which seemed to cause problems with displaying highlighting, line breaks, etc.
• Make sure highlighting is obvious enough visually and that snippets aren't too big that it makes it hard to look to scan many results at once (or to have to scroll down).
• Try to decrease the amount of visual change from each search. Right now the search transitions seem to slow down the page and also make a flashing effect.
• Potentially you could go with more of an autocomplete-style visual effect like React and our DocSearch sites. This might be more user friendly than changing the full page contents. You could still have a full-page search as a separate more advanced search page.

If you scroll down the page and then initiate a search, the scroll position is maintained and you end up looking at the middle or end of your search results. It would be good if you scrolled back to the top when searching.

There's no plugin store in Gitbook now. How to use this then please ?

It would be great to add a YAML attribute keyword to specify keywords for a page. These would be included in the created indexes.

As for the YAML attribute naming, in order to have good compatibility with other plugin configuration, we could namespace/prefix them to be specific enough. For example:

---
search_indexing: false
search_keywords: ["keyword1", "keyword2"]

---

or

---
search:
    indexing: false
    keywords: ["keyword1", "keyword2"]

---

instead of

---
search: false
keywords: ["keyword1", "keyword2"]

---

This search prefix would establish a convention for similar search plugins with different engines.

Hi,

Our GitBook, https://agolo.gitbooks.io/wiki/, stopped updating the Algolia index around 8 days ago. That would be around Sept 13. Here is a screenshot of the Algolia "Latest operations" list.

We didn't change any Gitbook settings on Sept 13. Our environment variable for the Admin key is still set correctly. However, at the bottom of each change's build log, we see the following message:

warn: Algolia indexation is disabled: 
warn: You need to configure the ALGOLIA_PRIVATEKEY environment variable using your Admin API Key. 

Our book.json has the following attributes:

{
    "plugins": [
        "simple-page-toc",
        "edit-link",
        "page-toc",
        "algolia",
        "mathjax"
    ],
    "pluginsConfig": {
        "edit-link": {
            "base": "https://www.gitbook.com/book/agolo/wiki/edit#/edit/master/",
            "label": "Edit This Page"
        },
        "page-toc": {
            "selector": ".markdown-section h1, .markdown-section h2, .markdown-section h3",
            "position": "top"
        },
        "algolia": {
            "index": "Agolo_Gitbook",
            "applicationID": "OUR APP ID",
            "publicKey": "OUR PUBLIC KEY",
            "freeAccount": "true"
        }
    }
}

We are on the free tier of Algolia, and today is the end of our first month on this plan.

Thanks for your help!

The issue here is to find the best suited behavior for the general use case of the Algolia plugin.

At time of writing, the plugin fails the gitbook build if ALGOLIA_PRIVATEKEY is not in the environment. If provided, the index is generated and uploaded every build (whether you are just working with gitbook serve on a local draft version, or building the real published version).

There are two type of people: those who can use the CLI and those who only use the Editor.

Current behavior

An author using the Editor only:

• is not able to use the Algolia plugin (cannot provide the ALGOLIA_PRIVATEKEY)
• needs to disable the plugin from the Plugin Store to pass the build on GitBook.com
• is immediately warned of this issue because the build fails. This is great to avoid confusing situation where the book is published but the Search is not working.

An author using the CLI:

• is able to use the Algolia plugin and generate the indexes
• must remember to turn off the plugin every time he gitbook build/serve and he doesn't want to actually publish the index.

Alternate behavior

An alternative is to just issue a warning during build time, but still pass the build if ALGOLIA_PRIVATEKEY is absent.

An author using the Editor only:

• still cannot use the Algolia plugin (cannot provide the ALGOLIA_PRIVATEKEY)
• can seamlessly continue to collaborate on the book, because the build are passing
• will only notice that the plugin failed when looking at the published book with Search not working.

An author using the CLI:

• is still able to use the Algolia plugin and generate the indexes
• only needs to remember to provide the ALGOLIA_PRIVATEKEY when he wants to regenerate the index (which is not easily forgettable because directly related to the intent: publish an indexed version)
• must remember to unset the env. variable before working again on drafts...

There is no way (that I can see) to close or hide the search results if you are done with them. Right now, the only way I can see to do that is backspace all the way back to the beginning of your search terms or to navigate to another page. A "X" icon or ESC key handler would be good to remove them without having to whack your keyboard a bunch of times or change pages and lose your place.

This would prevent losing the last index while the book is generated.