Logo

First steps

  • Getting Started with Sphinx
  • Getting Started with MkDocs
  • Importing Your Documentation
  • Read the Docs features
  • Choosing Between Our Two Sites

Getting started

  • Configuration File
  • Incoming Webhooks and Automation
  • Custom Domains and White Labeling
  • Versioned Documentation
  • Downloadable Documentation
  • Server Side Search
    • Search features
    • Analytics
    • API
      • Authentication and authorization
  • Preview Documentation from Pull Requests
  • Documentation Hosting Features
  • Connecting Your VCS Account
  • Build Process
  • Badges
  • Site Support
  • Frequently Asked Questions

Step-by-step Guides

  • Sphinx & MkDocs Guides
  • Read the Docs Guides
  • Read the Docs for Business Guides

Advanced features

  • Subprojects
  • Single Version Documentation
  • Localization of Documentation
  • User-defined Redirects
  • Automatic Redirects
  • Automation Rules
  • Public API

About Read the Docs

  • Contributing to Read the Docs
  • Developer documentation
  • Roadmap
  • Google Summer of Code
  • Code of Conduct
  • Security
  • Privacy Policy
  • Read the Docs Terms of Service
  • DMCA Takedown Policy
  • Policy for Abandoned Projects
  • Changelog
  • About Read the Docs
  • Read the Docs Team
  • Read the Docs Open Source Philosophy
  • The Story of Read the Docs
  • Advertising
  • Sponsors of Read the Docs
  • Read the Docs for Business
  • Info about custom installs
Read the Docs
  • »
  • Server Side Search
  • Edit on GitHub

Server Side Search¶

Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch. You can search all projects at https://readthedocs.org/search/, or search only on your project from the Search tab of your project.

We override the default search engine of your project with our search engine to provide you better results within your project. We fallback to the built-in search engine from your project if our search engine doesn’t return any results, just in case we missed something 😄

Search features¶

We offer a number of benefits compared to other documentation hosts:

Search across subprojects

Subprojects allow you to host multiple discrete projects on a single domain. Every subproject hosted on that same domain is included in the search results of the main project.

Search results land on the exact content you were looking for

We index every heading in the document, allowing you to get search results exactly to the content that you are searching for. Try this out by searching for “full-text search”.

Full control over which results should be listed first

Set a custom rank per page, allowing you to deprecate content, and always show relevant content to your users first. See search.ranking.

Search across projects you have access to (Read the Docs for Business)

This allows you to search across all the projects you access to in your Dashboard. Don’t remember where you found that document the other day? No problem, you can search across them all.

Special query syntax for more specific results.

We support a full range of search queries. You can see some examples in our Search query syntax guide.

Configurable.

Tweak search results according to your needs using a configuration file.

Analytics¶

Know what your users are looking for in your docs. To see a list of the top queries and an overview from the last month, go to the Admin tab of your project, and then click on Search Analytics.

Search analytics demo

Fig. 4 Search analytics demo¶

API¶

Search is exposed through our API that’s proxied from the domain where your docs are being served. This is https://docs.readthedocs.io/_/api/v2/search for the docs project, for example.

Warning

This API isn’t stable yet, some small things may change in the future.

GET /_/api/v2/search/¶

Return a list of search results for a project, including results from its Subprojects. Results are divided into sections with highlights of the matching term.

Query Parameters
  • q – Search query

  • project – Project slug

  • version – Version slug

Response JSON Object
  • type (string) – The type of the result, currently page is the only type.

  • project (string) – The project slug

  • project_alias (string) – Alias of the project if it’s a subproject.

  • version (string) – The version slug

  • title (string) – The title of the page

  • domain (string) – Canonical domain of the resulting page

  • path (string) – Path to the resulting page

  • highlights (object) – An object containing a list of substrings with matching terms. Note that the text is HTML escaped with the matching terms inside a <span> tag.

  • blocks (object) –

    A list of block objects containing search results from the page. Currently, there are two types of blocks:

    • section: A page section with a linkable anchor (id attribute).

    • domain: A Sphinx domain with a linkable anchor (id attribute).

Example request:

$ curl "https://docs.readthedocs.io/_/api/v2/search/?project=docs&version=latest&q=server%20side%20search"
import requests
URL = 'https://docs.readthedocs.io/_/api/v2/search/'
params = {
   'q': 'server side search',
   'project': 'docs',
   'version': 'latest',
}
response = requests.get(URL, params=params)
print(response.json())

Example response:

{
    "count": 41,
    "next": "https://docs.readthedocs.io/api/v2/search/?page=2&project=read-the-docs&q=server+side+search&version=latest",
    "previous": null,
    "results": [
        {
            "type": "page",
            "project": "docs",
            "project_alias": null,
            "version": "latest",
            "title": "Server Side Search",
            "domain": "https://docs.readthedocs.io",
            "path": "/en/latest/server-side-search.html",
            "highlights": {
                "title": [
                    "<span>Server</span> <span>Side</span> <span>Search</span>"
                ]
            },
            "blocks": [
               {
                  "type": "section",
                  "id": "server-side-search",
                  "title": "Server Side Search",
                  "content": "Read the Docs provides full-text search across all of the pages of all projects, this is powered by Elasticsearch.",
                  "highlights": {
                     "title": [
                        "<span>Server</span> <span>Side</span> <span>Search</span>"
                     ],
                     "content": [
                        "You can <span>search</span> all projects at https:&#x2F;&#x2F;readthedocs.org&#x2F;<span>search</span>&#x2F"
                     ]
                  }
               },
               {
                  "type": "domain",
                  "role": "http:get",
                  "name": "/_/api/v2/search/",
                  "id": "get--_-api-v2-search-",
                  "content": "Retrieve search results for docs",
                  "highlights": {
                     "name": [""],
                     "content": ["Retrieve <span>search</span> results for docs"]
                  }
               }
            ]
        },
    ]
}

Authentication and authorization¶

If you are using private versions, users will only be allowed to search projects they have permissions over. Authentication and authorization is done using the current session, or any of the valid sharing methods.

Next Previous

© Copyright 2010-2021, Read the Docs, Inc & contributors. Revision 33cb8878.

Built with Sphinx using a theme provided by Read the Docs.
Read the Docs v: latest
Versions
latest
stable
no-ranking
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds