New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We鈥檒l occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Documentation] Add a nice search experience in the website #1104

Closed
s-pace opened this Issue Aug 27, 2018 · 5 comments

Comments

Projects
None yet
3 participants
@s-pace

s-pace commented Aug 27, 2018

馃憢 jQuery team,

Following #227 that is lost in threads, I am following up and waiting fro feedback.

As web developers, we've all used jQuery in our career and we'll be forever grateful for how it changed the web development landscape for the better. But with so many versions along the years, we understand it can sometimes be hard to navigate into the documentation.

I'm working at Algolia on the a project called DocSearch which goal is to enhance documentation websites with exhaustive, fast and relevant search. You might have seen DocSearch live already on websites like Bootstrap, ESLint or Babel.

We put together a demo of what DocSearch on the jQuery website could look like here. Feel free to try it and let us know what you think.

demo of DocSearch + jQuery

The way DocSearch works is by crawling your content, pushing the results into an Algolia index, and then requesting this index directly from the website front-end through JavaScript.

We'll take care of crawling your website and populating the Algolia index with the latest changes every 24h for you. You don't need to change anything to your deployment process. The only thing you need to add are the following CSS and JS snippets that will bind the dropdown to your searchbox.

<!-- at the end of the HEAD -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.css" />

<!-- at the end of the BODY -->
<script type="text/javascript" src="https://cdn.jsdelivr.net/npm/docsearch.js@2/dist/cdn/docsearch.min.js"></script>
<script type="text/javascript"> docsearch({
  apiKey: '3cfde9aca378c8aab554d5bf1b23489b',
  indexName: 'jquery',
  inputSelector: '[name="s"]',
  debug: false // Set debug to true if you want to inspect the dropdown
});
</script>

The inputSelector option should be set to a CSS selector that target your search input. Feel free to update it if this one is not specific enough.

We built DocSearch with the idea of giving back to the Open-Source community. This is why your crawling configuration is available on GitHub if you want to change it. We also have our own documentation to help you tweak the dropdown to your needs. You'll also have access to analytics on the most searched terms or those with no results. All of this is of course entirely free.

Would that be something you'd be interested in? If so, we'd be happy to work on integrating it through a PR.

@timmywil

This comment has been minimized.

Show comment
Hide comment
@timmywil

timmywil Aug 27, 2018

Member

This looks pretty cool. I'm open to it, but would love to see how it looks on mobile and some data on how it affects page load.

Member

timmywil commented Aug 27, 2018

This looks pretty cool. I'm open to it, but would love to see how it looks on mobile and some data on how it affects page load.

@mgol

This comment has been minimized.

Show comment
Hide comment
@mgol

mgol Aug 27, 2018

Member

Thanks for the proposal! I see it requires 43 KB of gzipped JS; we currently load 128 KB of JS in total. As it's not a critical part of the site I'd rather see the script loaded async to not delay other stuff that may wait for document ready (i.e. the DOMContentLoaded event). Then you'll need to somehow wait for the script to execute so your inline snippet will need to look differently. Can that be done?

Member

mgol commented Aug 27, 2018

Thanks for the proposal! I see it requires 43 KB of gzipped JS; we currently load 128 KB of JS in total. As it's not a critical part of the site I'd rather see the script loaded async to not delay other stuff that may wait for document ready (i.e. the DOMContentLoaded event). Then you'll need to somehow wait for the script to execute so your inline snippet will need to look differently. Can that be done?

@s-pace

This comment has been minimized.

Show comment
Hide comment
@s-pace

s-pace Aug 28, 2018

Thanks for your feedback.

@timmywil our UI was initially designed for Desktop. It is mobile compliant but not really responsive, give it a try. You can easily tweak it thanks to CSS. The design/color can also be changed, see our guide on this.

We are designing the v3 of our search-UI and your concern @mgol is the biggest one. WIP.

The search script can definitely be loaded async and it will not impact the page load time.

Do you want to PR it?

s-pace commented Aug 28, 2018

Thanks for your feedback.

@timmywil our UI was initially designed for Desktop. It is mobile compliant but not really responsive, give it a try. You can easily tweak it thanks to CSS. The design/color can also be changed, see our guide on this.

We are designing the v3 of our search-UI and your concern @mgol is the biggest one. WIP.

The search script can definitely be loaded async and it will not impact the page load time.

Do you want to PR it?

@mgol

This comment has been minimized.

Show comment
Hide comment
@mgol

mgol Aug 28, 2018

Member

A PR would be very much welcome!

Member

mgol commented Aug 28, 2018

A PR would be very much welcome!

s-pace added a commit to s-pace/jquery-wp-content that referenced this issue Aug 28, 2018

s-pace added a commit to s-pace/jquery-wp-content that referenced this issue Aug 28, 2018

Component: Add DocSeach to jquery website
This commit will add DocSearch to the documentation website. It is the first step in order to fully integrate it.

Ref Bootstraping PR as jquery/api.jquery.com#1104
@s-pace

This comment has been minimized.

Show comment
Hide comment
@s-pace

s-pace Aug 29, 2018

馃殌

Everything ready on our side 馃挭 @Shipow

Please review it @mgol @timmywil and let us know what to do 馃檹

s-pace commented Aug 29, 2018

馃殌

Everything ready on our side 馃挭 @Shipow

Please review it @mgol @timmywil and let us know what to do 馃檹

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment