Content Search

Last updated:

HubSpot CMS has built-in site search functionality to allow your visitors to easily find the content they are looking for. All of your HubSpot content is automatically indexed in HubSpot’s native search engine, taking the hassle out of setting up a third-party search tool for your website.

Searching Content

The search engine is accessible through the /contentsearch/v2/search api. This API supports numerous filtering options to allow you to create a highly customized and powerful search experience on your website. For example, if you wanted to build a search into your blog, you can query for type=BLOG_POST to only return blog posts. Or, if you wanted to build search into the Spanish version of your website, you could query language=es to only return Spanish pages.

The API returns JSON that can be parsed with JavaScript to display the results on your website. All content types will return the page domain, title, url and language. The description returned is a sample of text from the content which best matches the search term. A <span class="hs-search-highlight hs-highlight-html"> element will wrap perfectly matching text, allowing you to highlight matching text with CSS. 

Depending on the type of content searched, the results return slightly different information, so you can display results for unique content types differently. For example, blog posts will return information on which tags the post has, who the author is, and when it was published.

JSON
// json
{
  "total": 850,
  "offset": 0,
  "limit": 10,
  "results": [
    {
      "id": 3761238962,
      "score": 0.30858153,
      "type": "SITE_PAGE",
      "domain": "designers.hubspot.com",
      "url": "https://developers.hubspot.com/docs/cms/search",
      "language": "en",
      "title": "Content Search",
      "description": "Using HubSpot’s native search engine, content search, to implement <span class="hs-search-highlight hs-highlight-html">search on your website</span>"
    },
    {
      "id": 3254581958,
      "score": 0.30858153,
      "type": "BLOG_POST",
      "domain": "designers.hubspot.com",
      "url": "https://designers.hubspot.com/blog/getting-started-with-local-development",
      "featuredImageUrl":"https://designers.hubspot.com/hubfs/local-development.jpg"
      "title": "Getting Started with Local Development",
      "description":"The beta Local Development Tooling connects your local workflow to HubSpot, allowing you to utilize <span class="hs-search-highlight hs-highlight-html">version control</span>, your favorite text editor and various web development technologies when developing on the HubSpot CMS."
      "authorFullName": "William Spiro",
      "tags": [
        "Website Development",
        "Local Development"
      ],
      "publishedDate": 1447938000000
    }
}

For the comprehensive documentation on query and result parameters, see the /contentsearch/v2/search documentation.

Implementing search on your website

There are two default modules you can use to easily implement search on your website, which utilize the /contentsearch/v2/search api. 

Site Search Input

An input field for visitors to enter search terms into. This module can exist anywhere on your website. This module can be included in a template with {% module "search_input" path="@hubspot/search_input" %}.

Site Search Results

Returns a listing of content based on the search term. This module can exist anywhere on your website. This module can be included in a template with {% module "search_results" path="@hubspot/search_results" %}.

If the functionality of these modules is not how you want search to work on your website, you can build your own search modules or functionality. The default search modules are designed to be extended based on your search needs. You can view and clone these modules in the Design Manager by searching for their names in the Finder, or, you can fetch them to your local environment using the CMS CLI by running hs fetch @hubspot/search_input.module or hs fetch @hubspot/search_results.module.

default search module

Search Results Template

Every domain has its own search results page by default. The template and path for this page are set at Settings > Website > Pages under the System Pages tab for specific domains. See the CMS theme boilerplate search results template as an example. The domain set for the search results page is automatically connected to the default search modules. However, you can build search however you please using the /contentsearch/v2/search api, on any pages of your website.

How is the search precedence determined?

The order of search results is determined by a series of weighted comparisons of page content to the visitor's search term. Page content is separated into comparison fields with varying weight based on where the content lives within the HTML of your pages. Comparison fields are grouped in order of weight:

  1. HTML title
  2. Meta description
  3. H1 HTML elements
  4. H2 HTML elements
  5. H3 HTML elements
  6. Other HTML elements

Please note that this list is subject to change. 

If you wish to tell our indexer to specifically boost certain elements on a page, you can wrap the content in a hs-search-keyword class.

How can I exclude pages from being returned in search results?

If you block a page from being indexed to search engines via your websites robots.txt file or via meta tags, they will not be indexed for search. Additionally, pages that are behind CMS Memberships are not indexed for search. 

Sometimes there are regions of a page that are not useful to return in search results. This might be content from a header, a footer, sidebar, etc. When this is the case, you can add the class hs-search-hidden to your HTML for those regions to have search ignore the content inside.