Installing Relevanssi is simple.
For free version, install the latest version of the plugin from WordPress.org plugin repository.
For Premium, download the latest version from Relevanssi.com and either upload the zip file using the WordPress plugin installation or unzip it and upload the files with FTP in the /wp-content/plugins/ directory.
After installing, check Settings > Relevanssi to adjust the settings and build the index.
Relevanssi doesn’t come with a search widget. You can use the default WordPress search widget or any other method that generates a standards-compliant search form.
On the overview tab, you’ll find the API key setting (Premium only). If you’re on a multisite network, the API key field is not here, it is in the Network admin dashboard.
Enter your API key here to enable automatic updates and PDF indexing. API key can be found here on Relevanssi.com – it’s in the sidebar when you’re logged in.
Hide Relevanssi on edit pages (Premium only) hides everything about Relevanssi from post edit pages.
All options on this tab affect the indexing and won’t have any effect until you build the index. You need to save the options before indexing. Clicking Build the index will wipe the index clean and rebuild the complete index, based on the indexing settings you’ve chosen on this tab. The indexing will run until it’s finished. It can take a while, especially on a large site, but the indexing process will show an estimate of the remaining time. Keep the browser window open as long as it takes to index.
If for some reason the indexing is interrupted, you can click the Index unindexed posts. This will index all the remaining posts (including all post types). This button can be useful if you import posts in a way that doesn’t trigger Relevanssi indexing: just click the button after the import to index all the new posts.
State of the index shows the number of documents (posts, pages), users and taxonomy terms (Premium only) in the index, number of terms (words) in the index and the highest post ID in the index. These are useful for debugging purposes, for example to see if the indexing works.
Just check the boxes for each post type you wish to include in the index. The “Excluded from search?” column shows whether the post type is marked public or not, but it doesn’t mean you can’t index those post types. It’s just for information.
Choose which taxonomies are indexed for the posts. If you check a taxonomy here, it means that searching for the taxonomy term name will find all posts that have this taxonomy term attached to them. Again, the “Public?” column is just for your information.
Choose which comments are indexed. You can choose to include only regular comments or also include pingbacks and trackbacks.
Choose which custom fields are indexed. “All” includes all custom fields assigned to a post, “visible” only those that are shown on the edit page. If a custom field name starts with an underscore (_), it is hidden from the post edit page, and won’t be included if this setting is set to “visible”. Since some themes can add quite a bit of behind-the-scenes data in the custom fields, “visible” is a reasonable setting. You can also choose to index only specific fields you list.
Relevanssi Premium supports ACF repeater fields, using the notation
Author display names
If this option is enabled, Relevanssi will index author display names. Searching for an author will find all posts written by the author.
If this option is enabled, Relevanssi will index post excerpts.
If this option is checked, Relevanssi will expand all shortcodes in post content before indexing the post. That means the shortcode content will be included in the index. This doesn’t always work as expected. If the shortcode provides dynamic content, Relevanssi will index the post with the content at the moment of indexing, and won’t update the index when the dynamic content changes.
Some plugins don’t enable their shortcodes in the admin side, so Relevanssi can’t expand them. Some plugins, especially those that don’t respect WP programming standards, may break Relevanssi. If indexing doesn’t work, one of the first things to try is to disable this option.
Disable these shortcodes (Premium only)
You can list unwanted shortcodes here: if a shortcode is causing problems in indexing, list it here and it will be disabled when Relevanssi indexes posts.
Index user profiles (Premium only)
If this is checked, Relevanssi will index user profiles. Relevanssi indexes first name, last name, display name and user description. You can also index other data for users, see two options down.
Since WordPress expects the search results to be posts, Relevanssi needs to convert the user profiles to posts. That requires some changes in your search results template.
the_permalink() should work in most cases, pointing to the user profiles. See User profile search for more information.
Index subscribers (Premium only)
If checked, Relevanssi will also index subscribers, otherwise only admins, editors, authors and contributors are indexed.
Extra fields (Premium only)
If you want to index other user fields, you can list them here. These field names should correspond to MySQL database columns in the
wp_user table or user custom fields.
Index synonyms (Premium only)
Synonyms generally only work in OR searches: the synonyms are used by adding more words to the search query and in OR search that works as expected, widening the search. In AND search, it will restrict the search, so it won’t work. Enabling this option will make Relevanssi index the synonyms as part of the post content, making them compatible with AND searches.
Index taxonomy terms (Premium only)
If you enable this option, you can index taxonomy term pages. If this option is enabled, searching for a taxonomy term name will return the term archive page as a result. By default, Relevanssi only indexes those terms that are attached to posts. With this option enabled,
get_permalink() won’t work on search results template.
the_permalink() does, but if you don’t want to echo the permalink, you can use
relevanssi_get_permalink() instead. See Indexing taxonomy pages.
Taxonomies controls which taxonomies are indexed.
Index for parent (Premium only)
If checked, Relevanssi indexes the PDF content both for the attachment post and the parent post. You can control the attachment post visibility by indexing or not indexing the post type
Advanced indexing settings
Minimum word length
Enter an integer. Words shorter than this many characters are not indexed. The default value 3 is pretty good for English, for other languages other values may make sense.
By default Relevanssi removes some punctuation completely and replaces the rest with spaces. These fields give you control over the most common punctuation types: ampersands, hyphens, dashes, apostrophes and quotes. You can define the behaviour for all of these classes. The correct settings depend on what kind of content you want to search, but the default values make sense in most cases.
Thousands separator (Premium only)
This option helps indexing large numbers. Particularly in languages like Finnish where the thousands separator is a space, you can enter space here and have numbers like “1 000 000” indexed correctly as “1000000”. Since Relevanssi replaces periods and commas with spaces, using this option will make sense with those separators as well.
MySQL columns (Premium only)
If you have a plugin that writes the data in a custom column in
wp_posts MySQL table, you can add the column name here to have that data indexed.
Internal links (Premium only)
This option sets how Relevanssi handles internal links (links that point to your own site). If you choose “No special processing”, Relevanssi doesn’t care about links and indexes the link anchor (the text of the link) like it is any other text. If you choose “Index internal links for target documents only”, then the link is indexed like the link anchor text were the part of the link target, not the post where the link is.
Attachments (Premium only)
Attachment tab handles the PDF content reading. If you have PDF files in your Media Library, Relevanssi can read in the PDF contents so that they are available for indexing.
In order to read the contents of the PDFs, the files are sent over to Relevanssiservices.com, a PDF processing service hosted on a Digital Ocean Droplet in the USA. The service creates a working copy of the files. The copy is removed after the file has been processed, but there are no guarantees that someone with an access to the server couldn’t see the files. Do not read files with confidential information in them. In order to block individual files from reading, use the Relevanssi post controls on attachment edit page to exclude attachment posts from indexing.
Read all unread PDFs reads in all the PDF content in attachments. This does not wipe the index, and will only process those PDFs which haven’t been read yet. If reading the PDF caused an error message before, the PDF will be skipped, unless the error message is a time out, in which case it’s attempted again.
Reset all PDF data from the posts will empty out the PDF information from the posts. It is stored in the attachment metadata: content in
_relevanssi_pdf_content and errors in
_relevanssi_pdf_error. Clicking this button will wipe these custom fields empty.
Upload PDF files
By default Relevanssi sends a link to the PDF to the reading service, which then downloads the PDF and reads it. However, if your files are behind a firewall, in an intranet or otherwise not accessible from the outside world, this is not going to work. In that case, check this option, and Relevanssi will upload the files directly.
Link to PDFs
If you decide to have attachments in search results (by indexing the
attachment post type), by default the links in search results pages will lead to the attachment page. That’s often less than helpful, as it’ll take one more click to reach the actual PDF. Enabling this option will make the search results pages link directly to the PDF file.
OR search will return all posts where at least one of the search terms appears. AND search will only return posts that have all search terms in them. OR search will prefer posts that have all search terms in them, so in most cases it is the better option.
Fallback to OR
If you have chosen AND as the default operator and the search finds no results, Relevanssi will perform an OR search with the same search terms. If you want to disable this, check this option.
By default Relevanssi orders results by relevance, trying to put the most relevant results first. This makes a lot of sense. Some people prefer other methods. From the settings page, you can choose post date order, most recent posts first. If you want other orderings, you can use the
orderby parameter. For multiple levels of ordering, Relevanssi supports array
Relevanssi can match whole words or partial words. Matching whole words means only complete words are matched. If you search for “ledge”, you will only find documents that contain the word “ledge”. Partial words also matches parts of words, so searching for “ledge” will also finds documents that contain words “knowledge” and “ledger”.
The search term has to be either in the beginning or the end of the word, so searching for “ion” will find “caution” or “ionized”, but not “cautionary”.
Here you can adjust weights for different features like post titles, tags, comments, different post types or taxonomies. Some of these adjustments are Premium only. All the weights work the same way: they are multipliers, so 1 keeps the weight neutral compared to everything else, below 1 makes the weight smaller and values over 1 make the particular item weigh heavier in the matching.
If you want to emphasize something, don’t be afraid of using big numbers. If you want to make sure that posts with the search terms in titles come up in the search, slap a weight of 100 or 1000 for the titles. Subtlety is overrated.
Recent posts bonus cutoff (Premium only)
If you’ve added extra weight for recent posts, this option determines which posts are considered recent.
If you enable this option, Relevanssi will be enabled for admin searches. Otherwise default WordPress search will be used in all searches in the admin interface. Admin searches may not always work very smoothly. For example page search will not use Relevanssi, because that’s just how WordPress works.
If you check this option, custom post types which have
exclude_from_search set to true will be excluded from the search. If the option is unchecked, Relevanssi won’t respect that setting and will search anything that is indexed.
On large sites searches can become heavy to process, particularly when there are common words involved. Relevanssi has to load every post that is found by any search term, and that can require lots of memory. In most cases, the user only cares about the few posts on the first page of search results.
This option will restrict Relevanssi to only first 500 posts per search term. Relevanssi will only take the first 500 posts per search term, so the maximum number of posts Relevanssi will load in memory is 500 times the number of search terms. The 500 posts are chosen with some sense, so it is very likely the best posts are within those 500 posts. This way the search becomes more effective and less memory-intensive. On a small site this option isn’t necessary – if a single search term finds less than 500 posts, the limit of 500 doesn’t make any difference – but on a large site this is very useful option, and I recommend you use this option all the time.
Do note that choosing the probably best posts only works with the relevance ordering. If your order posts by date, it is quite likely the limit will drop out useful posts. If you need to have the limit and you want posts ordered by date, I suggest you set Relevanssi to relevance order, use a limit and then use
orderby parameter to sort the results by date.
If you want to restrict search to a particular category, you can do it here.
You can also use the input field ‘cats’ to do this on a search form basis, that’s the more flexible way to handle this. If you use both the input field and this option, the input field will overrun this.
Here you can permanently exclude categories from search. The ‘cats’ input field also takes negative values for exclusion.
If you want to permanently exclude posts or pages from search, you can list their numeric IDs here. In Premium, you can also use a checkbox on the edit pages to exclude posts. That is easier to use and works in multisite searches, unlike this option.
Keep a log of user queries
If you enable logging, then you’ll find the searches logged and presented in Dashboard > User searches. Logs are necessary for the Did you mean function to work in the free version.
Log user IP
Enable this option to log the user IP addresses. Do note that this may be illegal in your jurisdiction, or require GDPR paperwork. The IP addresses are not visible on the User Searches page, but can be found in the wp_relevanssi_log database table.
If you want to disable logging for particular users (like yourself), add a list of comma-separated numeric user IDs or login names here. “admin” is a good start, unless you’ve changed the main user login name.
Hide Relevanssi branding (Premium only)
Useful option if you’ve installed Relevanssi on a client page, this will remove all Relevanssi branding on the user searches screen, so your client won’t be confused.
The log database can get large. It is possible to automatically trim the logs. Enter a number here, and the logs older than that many days will be automatically removed.
Excerpts and highlights
Custom search result snippets
To have Relevanssi create custom excerpts highlighting the hits in searches, you need to enable this option. Relevanssi will then replace the post excerpt with something it has created on the fly (so the original post excerpt is overwritten, but only for the particular search, not permanently; also, the original excerpt is available in
To see the excerpts, make sure your search results template is using
the_excerpt(). If your search results template uses
the_content() or something else to show the post content, it’s possible you won’t see the Relevanssi excerpts.
Length of the snippet
Choose the length of the excerpt, either in words or in characters. Use words, it’s many times faster than using characters.
Allowable tags in excerpts
List of all HTML tags that should be allowed in the excerpts. List the tags without any whitespace, like this: <p><a><strong>.
Use custom fields for excerpts
If you are searching custom fields, by default Relevanssi doesn’t use the custom field content to build excerpts. If you check this option, Relevanssi will use the custom fields it is indexing as a source material for excerpts.
Here you can choose the method of highlighting used: <mark>, <em> or <strong> tags, text colour, background colour, CSS style or CSS class. CSS style means you later enter CSS stylings, which are used for highlighting (<span style=”your style”>). If you wish to keep styles in separate files, use CSS class (<span class=”your class”>).
Highlight in titles
Titles are not highlighted unless you enable this option. You also need to replace
the_title() in the search results template with
Highlight in documents
If you check this option, the search terms are also highlighted in the posts that are opened from the search results. This requires an extra parameter (
highlight) to the links from the search results pages so in order to get these highlights, you need to use
relevanssi_the_permalink() to print out the permalinks on the search results templates.
Highlight from external searches (Premium only)
Highlights search terms from external searches. Currently this feature works with Bing, Ask, Yahoo and AOL searches. Support for other search engines is available on request, but Google is not an option.
Highlight in comments
If you enable this option, Relevanssi highlights query terms in comment text, when you open the post from the search results page.
Highlighting problems with non-ASCII alphabet?
Most people need not uncheck this, but if you’re using for example Cyrillic alphabet and the highlighting doesn’t work properly, unchecking this option will help. By default the highlighting regexp is using word boundary markers, and those do not always work properly with non-ASCII characters.
Breakdown of search hits in excerpts
If this is checked, Relevanssi will add extra information in the end of the search result excerpts.
The breakdown format
If you enabled the breakdown, this option determines what is shown. There are couple of keywords you can use:
%comments% show the number of hits in body, title, tags and comments.
%total% shows the number of hits in total.
%score% shows the relevancy score of the post.
%terms% shows how many hits each search term has. Try and see how each one of these works,
%terms% are the most interesting keywords in most cases.
Synonyms can be used to make search more powerful. If you have for example lots of abbreviations in your posts, but some posts use the non-abbreviated form, you can make those two synonyms for each other. Searching for one will find the other.
Synonyms are entered as “word=word” pairs. The pairs are one-way, so if you enter “sdj=spiel des jahres”, any searches for “sdj” will be expanded to search for “spiel des jahres” as well, but it doesn’t work the other way around. If you want two ways, enter both.
Synonyms only work with OR search, where it’s possible to expand search by adding more terms to it (because that’s what synonym expansion does). In AND search, adding more words restricts the search further. In order to use synonyms in AND searches, you need to enable the indexing setting to index synonyms (Premium only).
Stopwords are words that are not indexed. Large part of any text will consist of support words that are pointless for searching. Those meaningless words would still be the biggest part of the index, were they left in.
Relevanssi has stopword lists for English (both US and UK), Portuguese (both Portuguese and Brazilian), Polish, French, Finnish, Spanish and German. The plugin should load in the correct stopword file based on your blog language setting. You can see the list of current stopwords on the settings page. If you want to remove a word, just click on it. You can also add stopwords.
If you add a stopword, it is automatically removed from the index, so you don’t need to reindex to see the effect. If you remove a stopword, it won’t be returned to index without a reindex.
25 most common words in the index
This list shows the 25 most common words in your index. These words often make good stopword material, so if you want to, you can click the icon after the word to make it a stopword.
Import or export options (Premium only)
This field contains all the Relevanssi options in serialized text format. You can simply copy them and paste them on another Relevanssi installation to copy the settings. Make sure both installations are running the same version of Relevanssi before you import settings, though.