Optimize search

Resources in this category will give you tools to help optimize or tweak your search results.

We're often asked how people can optimize--or dial in--their search results.

This is a multi-step process.

First: we only recommend tweaking your search weights or other settings once you have some concrete, specific examples to test with. Optimizing search for one scenario can sometimes cause poorer search results for another, so it helps to have a few examples of search phrases you want to test with, so you can test the before/after effects of making any changes.

If you have a few good examples handy (as well as some examples that you want to be sure won't be negatively impacted by your changes), here are our recommended steps:

Most search options are controlled in the Settings > Search menu.

So this first tip is a fairly straightforward one: take a quick look through the options available here and be sure you're using--or not using!--settings that make sense for your content.

Options here include controls for:

  • how your results appear (pagination, sorting, fuzzy search, your article blurbs, whether glossary terms are included)
  • whether readers can filter your search results by top-level or second-level categories
  • whether to use autosuggest results as people type their search phrase, and what the behavior for that autosuggest is
  • if certain things should be included or excluded from search results (child shared content articles, an entire category, PDFs longer than 100 pages)

For a full breakdown of these settings, check out Configure Search.

We automatically index the content in six article fields for search:

  • Title
  • Permalink/URL
  • Body
  • PDFs
  • Meta description
  • Search phrases

So the first step to "tuning" your search isn't really about search at all: it's about making sure that your content is well-structured in each of those fields.

Here are some key questions to get you started:

  • Does the title present keywords that your readers might search for?
  • Does the permalink present similar keywords?
  • Does the body of your article contain the words and phrases people are most likely to search for?
  • Do your articles consistently use the same word for the same concept, feature, or function? (This can include the article body, title, and permalink.)
    • This one can be easy to overlook, but if your knowledge base has evolved over time and there are older sections that haven't been updated in a while, you might be surprised!
  • If you are including PDFs stored in KnowledgeOwl as hyperlinks or embedded in iframes, do they use similar terminology to your article body so that they still surface relevant content?
    • Sometimes, PDFs are written by a different team or department and they use totally different terminology. This can skew search results in odd ways or surface entirely irrelevant content.
      Try to take a holistic approach here: any file of any type referenced in your knowledge base should use some key terminology the same way, wherever possible!
  • Are you consistently adding a meta description to your articles?
    • This is an easy field to miss, since it's so far down in the editor, but it's a great practice for maximizing SEO on public knowledge bases. 
    • If your knowledge base isn't public, it's still a fabulous field to use here, since it's basically a free indexing field. And, depending on your other settings, it may help display relevant information on category pages and in search results, too.
  • Are you using search phrases? If not, see Use search phrases for more info!

The Search Weights controls available in Settings > Search let you set relative weights that will be used by the search ranking algorithm to determine the order of results returned. This lets you dial in your search a bit to fit your content.

By default, all six of the fields we index for search (article title, permalink, body, PDFs, meta description, and search phrases) are given an equal weight of 1. Giving a field a higher index will boost its importance in the relevancy.

A brief warning: We recommend only touching search weights once you have a fair amount of content and/or once you've gotten feedback from readers that they've had trouble finding something.

The best way to make changes here is to have a few specific examples to test with.


  1. Go to Settings > Search.
  2. In the Search Testing box, enter one of your test search phrases. Note the relevancy scores and order it gives back to you.
  3. Make changes to the field(s) you think need higher search weights in the Search Weights section. We recommend only going up by the next available increment in the dropdown to start. Don't save your changes yet. 😉
  4. Now rerun your test search phrase in the Search Testing box. See if you've gotten closer to the order you're looking for.
  5. Test with multiple phrases to be sure that you haven't optimized for one scenario but hurt another one. (This is the tricky part of touching your search weights!)
  6. Once you've found a weight you like, Save your changes.

You won't need to reindex or anything--those weight changes will take immediate effect. If your weights are getting closer but still not amazing, see the next tip on search phrases!

See Search Weights and Search Testing for more details.

As an example, here are the search weights we're currently using in support.knowledgeowl.com:

Screenshot showing the search weights used in support.knowledgeowl.com. The weights are: Title: 10; Permalink: 1; Body: 1; PDFs: 1; Meta description: 1; Search phrases: 30The search weights we use in support.knowledgeowl.com

By now, I hope you've picked up on the fact that you don't need to do anything for your content to be indexed for search--it just is.

So why do we include search phrases, if we're already indexing the title, permalink, body, PDFs, and meta description?

To give you more control.

Search phrases serve two main purposes:

  1. You can add a search phrase that doesn't appear in the body of the article. This can be really helpful if there's an alternate phrase or term that your readers might use that you don't want in the documentation itself, like an acronym or abbreviation.
    • For this use case, you don't need to do anything else special--just add the search phrase. (And if you have a lot of these, see our next search optimization tip on synonyms--you're gonna love them!)
  2. You can add a search phrase to "bump up" a select number of articles that contain that phrase. So if you have 50 articles all of which mention the word "cheese", you might add "cheese" as a search phrase only to the 3-5 most important articles about cheese. This lets you game the ranking algorithm just a little.
    • In this scenario, you'd likely want to increase the search weight of Search Phrases so that they'd be weighted a bit more. (We do this in our Support knowledge base, using a search weight of 30 for search phrases.)

This second setup can be really useful when you use a term in a lot of your documentation, but you want to curate some articles to return at the top of the search when that term is searched.

Again, you don't need to change any settings or reindex to use this option; you just need to add relevant search phrases to your article and save it.

Pro tip: if you want to audit where search phrases are used, you can head over to Manage Articles and take a CSV export of any view there--you can choose to include the Search phrases column in your CSV export!

Synonyms are one of the unsung heroes of your knowledge base. You probably don't know they're there, but they can make a huge difference to how you write your content--and how it's indexed.

Synonyms' entire purpose is to help your search index work harder and do more.

Let's return to that first use case we mentioned for search phrases:

You can add a search phrase that doesn't appear in the body of the article. This can be really helpful if there's an alternate phrase or term that your readers might use that you don't want in the documentation itself, like an acronym or abbreviation.

So, for example, in our documentation, we use the phrase "knowledge base" a fair amount. We believe strongly in the two-word format. It's in our style guide.

This is great, from a content creator's perspective: we're totally consistent in our content.

But we get a lot of readers who might search for various permutations of that word, including:

  • knowledgebase
  • kbase
  • k base

Now, one way to address this would be to add a search phrase for each of these variations to every article where we use the phrase "knowledge base". That would solve the problem--someone searching for one of these variations would get to the content they need.

But that puts a lot of pressure on us to remember to do that.

And what happens if we find out next week that people start searching for "base site" or something else? We'd have to go manually edit all those articles to have that search phrase, too.

This is where synonyms really shine.

You define the synonym once, then you reindex your knowledge base, and our search indexing does that work for you.

So in our case, we never worry about adding "knowledgebase" or "kbase" as a search phrase, because we have a global synonym defined for it. And we can go update that synonym at any time and (once we run a search reindex) it will take effect across all of our articles.

Synonyms are fantastic for things like:

  • Variations of the official term you use for something
  • Acronyms or abbreviations your readers might search for that correspond to official terms--this way you don't necessarily have to include both the fully-written-out term and the acronym in every article

The one key here is that after you create synonyms, you will need to reindex your knowledge base to see them take effect. Reindexing can take a couple minutes and it will knock out search results while it runs, so it's generally best to time your reindexes for off-hours.

So you've gotten your search behaving fairly well overall, and things seem to be humming along great: you've gotten the settings how you like them, your content's using consistent terminology, you've tweaked your search weights a little, and you're using search phrases or synonyms to really stretch search.

Now what?

Generally, if you don't get complaints about people being unable to find things, there's not a whole lot else to do.

But if you like to keep an eye out for potential synonyms, content gaps, or search phrase needs, check out the Searches with no results report in Reporting > Dashboard.

This will help you identify words or phrases that your readers are searching for and coming up empty. Sometimes these are great candidates for synonyms or search phrases; sometimes they alert you to content gaps; sometimes they can even clue you in to features that your product or company is lacking.

In an ideal world, you'd want to include reviewing this report into a regular content update habit, though the frequency of this depends on how high your knowledge base usage is.