Thursday, 21 June, 2018 UTC


Summary

The Electron website has a new search engine that delivers instant results for API docs, tutorials, Electron-related npm packages, and more.

Learning a new technology or framework like Electron can be intimidating. Once you get past the quick-start phase, it can be difficult to learn best practices, find the right APIs, or discover the tools that will help you build the app of your dreams. We want the Electron website to be a better tool for finding the resources you need to build apps faster and more easily.
Visit any page on electronjs.org and you'll find the new search input at the top of the page.
The Search Engine
When we first set about adding search to the website, we rolled our own search engine using GraphQL as a backend. GraphQL was fun to work with and the search engine was performant, but we quickly realized that building a search engine is not a trivial task. Things like multi-word search and typo detection require a lot of work to get right. Rather than reinventing the wheel, we decided to use an existing search solution: Algolia.
Algolia is a hosted search service that has quickly become the search engine of choice among popular open source projects like React, Vue, Bootstrap, Yarn, and many others.
Here are some of the features that made Algolia a good fit for the Electron project:
  • InstantSearch.js provides results as you type, usually in about 1ms.
  • Typo tolerance means you'll still get results even when you type widnow.
  • Advanced query syntax enables "exact quoted matches" and -exclusion.
  • API clients are open source and with well-documented.
  • Analytics tell us what people are searching for most, as well as what they're searching for but not finding. This will give us valuable insight into how Electron's documentation can be improved.
  • Algolia is free for open source projects.
API Docs
Sometimes you know what you want to accomplish, but you don't know exactly how to do it. Electron has over 750 API methods, events, and properties. No human can easily remember all of them, but computers are good at this stuff. Using Electron's JSON API docs, we indexed all of this data in Algolia, and now you can easily find the exact API you're looking for.
Trying to resize a window? Search for resize and jump straight to the method you need.
Tutorials
Electron has an ever-growing collection of tutorials to complement its API documentation. Now you can more easily find tutorials on a given topic, right alongside related API documentation.
Looking for security best practices? Search for security.
npm Packages
There are now over 700,000 packages in the npm registry and it's not always easy to find the one you need. To make it easier to discover these modules, we've created electron-npm-packages, a collection of the 3400+ modules in the registry that are built specifically for use with Electron.
The folks at Libraries.io have created SourceRank, a system for scoring software projects based on a combination of metrics like code, community, documentation, and usage. We created a sourceranks module that includes the score of every module in the npm registry, and we use these scores to sort the package results.
Want alternatives to Electron's built-in IPC modules? Search for is:package ipc.
Electron Apps
It's easy to index data with Algolia, so we added the existing apps list from electron/apps.
Try a search for music or homebrew.
Filtering Results
If you've used GitHub's code search before, you're probably aware of its colon-separated key-value filters like extension:js or user:defunkt. We think this filtering technique is pretty powerful, so we've added an is: keyword to Electron's search that lets you filter results to only show a single type:
  • is:api thumbnail
  • is:tutorial security
  • is:package ipc
  • is:app graphql
Keyboard Navigation
People love keyboard shortcuts! The new search can be used without taking your fingers off the keyboard:
  • / focuses the search input
  • esc focuses the search input and clears it
  • down moves to the next result
  • up moves to the previous result, or the search input
  • enter opens a result
We also open-sourced the module that enables this keyboard interaction. It's designed for use with Algolia InstantSearch, but is generalized to enable compatibility with different search implementations.
We want your feedback
If you encounter any issues with the new search tool, we want to hear about it!
The best way to submit your feedback is by filing an issue on GitHub in the appropriate repository:
  • electron/electronjs.org is the Electron website. If you don't know where to file an issue, this your best bet.
  • electron/algolia-indices is where all the searchable Electron data is compiled.
  • electron/search-with-your-keyboard makes the search interface navigable by keyboard.
  • algolia/instantsearch.js is the browser-side client that enables find-as-you-type search.
  • algolia/algoliasearch-client-javascript is the Node.js client for uploading data to Algolia's servers.
Thanks
Special thanks to Emily Jordan and Vanessa Yuen for building these new search capabilities, to Libraries.io for providing SourceRank scores, and to the team at Algolia for helping us get started. 🍹