Customer StoriesReadMe Blog
Guides

Search + Search API

Suggest Edits

Overview

We have implemented a more powerful search using Algolia to help your users find the articles they are searching for even faster.

You can find the search in the fixed navigation bar:

As you type, the entire project is searched, with the search term underlined. Users can also filter the query down to specific sections to get more accurate results.

You can also operate Search by using keyboard shortcuts and typing CMD + k.

Search Ranking

Understanding search result ranking can help you optimize your content based on relevance in search results. Algolia manages several attributes, and we define custom attributes to combine and ensure that users are shown the most relevant and valuable results based on their search queries. Here's a detailed look at how we rank search results.

Ranking Attributes

  1. indexRank (custom attribute)
    1. Description: ReadMe defines this attribute, which is tagged on each record when we push them to Algolia. It maps to the type of content module, such as guides, references, or recipes.
    2. Priority: Highest
    3. Details: Guides, references, and recipes all have a value of 1, meaning they are weighted equally. This is why guides sometimes rank first, and references or recipes might rank in other instances.

Example code:

const indexRankings = {
  Guides: 1, // Guide Page
  Ref: 1, // API Reference (endpoints) Page
  Tutorial: 1, // Recipes
  Blog: 2, // Changelog
  CustomPage: 2, // Custom Pages
  Discuss: 3, // Discussion Post
};

  1. words
    1. Description: The number of words from the query that matched at least once.
    2. Priority: Second
  2. typo
    1. Description: Results with more typos will be ranked lower.
    2. Priority: Third
  3. proximity
    1. Description: How physically near the matching query words are in the record.
    2. Priority: Fourth
  4. exact
    1. Description: Number of query words matching exactly (without prefix matching).
    2. Priority: Fifth
  5. importance (custom attribute)
    1. Description: ReadMe defines this attribute, which maps to HTML/markdown headers (e.g., h1, h2, h3).
    2. Priority: Sixth
    3. Details: Helps prioritize content based on its structure in the document.

Priority Order

The order of these attributes is also their priority in ranking the results:

  1. indexRank

  2. words

  3. typo

  4. proximity

  5. exact

  6. importance

Indexing Limitations

In order to deliver the fastest possible search experience, Algolia does not index every single character on every single page in every project. Indexing for search is subject to the following limitations:

  • Up to 3,000 characters including spaces and punctuation following every heading
  • Up to about 400 words in tables (it varies slightly depending on how many columns there are due to how tables are stored in raw text)
  • No raw HTML
  • The following separators are not indexed: !#()[]{}*+-_一,:;<>?@/\^|%&~£¥$§€`"'‘’“”†‡

Here a few best practices that help ensure most or all of your content is indexed for search:

  • Add sub-headings to break up large chunks of text—users often entirely skip paragraphs longer than about 200 words in any case
  • Separate large tables into multiple smaller tables
  • Avoid wrapping important content in raw HTML

Enterprise Global Search

If you have several projects unified under an Enterprise Group, search will work across all the projects under that domain. Users will also be able to search only specific projects to limit the results that are returned.

Search API

👍

New Search API!

You can now use our new Search API

To use the search API, make a call to

https://{{project}}.readme.io/api/search?q={{query}}.

Updated 3 months ago