Documentation
Community Search
Community Search empowers your community members & product users to find everything they need from a single search. That includes documentation and community conversations on channels like GitHub, Discord, Discourse, and more. The search uses data that’s already in your Orbit workspace, so it’s easy to get up and running with. Read more about the motivation behind Community Search in the introductory blog post.
Try it now: Click the search box in the navbar 👆 and type a few queries to see how Community Search works. You’ll notice results coming from different places like the Orbit documentation, Discord, GitHub, and Twitter.
Step-by-Step Guide
In this guide, we’ll cover:
- Provisioning your search
- Choosing where to deploy it
- Adding the embed code
- The standalone search page
- Trust & safety
- Advanced features
1. Provision your search
To provision your search, there is a small step we need to take on the Orbit side. Email us at [email protected] and let us know:
- the workspace you’d like the search for
- any exceptions that you don’t want to be part of the search e.g. specific community channels; by default the search only includes information visible to the whole community
- any documentation sites that you’d like included in the search
In less than a day we’ll send you a link to your widget that you can test out. Once you’re happy with the search, you can deploy it anywhere 🚀
👉 Note: A self-service option and self-serve management controls are coming early next year.
Supported conversational data sources
- GitHub (issues & PRs)
- GitHub Discussions
- Discord (chat and forum channels)
- Discourse
Supported doc & reference data sources
- All major documentation platforms including Docusaurus, Gitbook, etc.
- Any public-facing website
2. Choose where to deploy the search
Once your search is provisioned, the next step is to decide where to deploy it. Here are a few of the most common choices.
Product Documentation
Add Community Search to your documentation. Since Community Search indexes your product documentation, users will still be able to find all the information. Only now, they’ll also see results from GitHub, Discord, and/or wherever else your community lives. Community Search replaces your existing search bar.
Community Search’s documentation indexing is based on the tried-and-true Algolia DocSearch scraper, used by thousands of documentation sites. This leads to a high-quality search with hierarchical results, smart ranking, typo tolerance, keyword highlighting, and search-as-you-type speed. The search is also tailored to the specific structure of your site and provides great results for common documentation providers like Docusaurus.
👉 Currently using Algolia DocSearch? If you’d prefer not to migrate to a different indexing solution, just let us know. Community Search can connect directly to your existing Algolia DocSearch instance and serve results from there. The Community Search widget will include the required “Powered by Algolia” branding.
Inside Your Application
Add Community Search to your application. Give users access to all of your product & community knowledge without leaving the app. Deploy the search as an icon in the corner or launch it when a users clicks on a specific link or menu item. See an example of this in the Orbit application.
Web Site / Marketing Site / Blog
Add Community Search to your web site, marketing site, or blog. Launch the search with a corner icon or add a search bar in the site header. See an example of this on the Orbit homepage.
Developer Portal / Community Site / Community Forum
Add Community Search to your developer portal, community site, or community forum. In each context, let users launch the search in the most natural way. All of these options are available:
- search bar
- bottom corner icon
- inline embed
- custom - launch-on-click from any HTML element
Discord Bot / Slack Bot
🤖 Coming soon! Reach out and let us know you’re interested to be the first to get access.
3. Embedding the widget
In this part of the guide, we’ll look at the code used to embed the widget and the options that are available for configuring it.
Get the Code
Here’s the block of code that can be added to any website. Replace <widget-id>
with the id of your search. You’ll be given this by the Orbit team.
<script type="text/javascript">
window.CommunitySearch = Object.assign({}, window.CommunitySearch, {
baseUrl: "https://search.orbit.love/widget/<widget-id>"
});
if (window.CommunitySearch.init) {
window.CommunitySearch.init();
}
</script>
<script src="https://search.orbit.love/widget.js" async defer></script>
Technical note: The Community Search modal loads in a secure iframe. It does not access information on the page it is embedded in, nor does it add any additional third-party scripts to the page. The only code that runs on the page is in widget.js. Feel free to inspect the unminified source code. When the script is loaded with async and defer options (recommended) it will not impact the performance of the page.
By default, this will add an icon in the bottom right corner of the screen. Users can click the icon to launch the search in a full-screen modal. Read on to learn about more options.
window.CommunitySearch options
Options are included inside the options
attribute of window.CommunitySearch
. Here’s an example followed by all of the available options.
window.CommunitySearch = Object.assign({}, window.CommunitySearch, {
baseUrl: "https://search.orbit.love/widget/<widget-id>",
options: {
docResultsLinkTarget: "_top"
}
});
docResultsLinkTarget
Determines whether links to documentation search results open in the same tab or a new tab (default). Supported values are _top
and _blank
. We recommend setting the value to _top
when the widget is embedded inside the documentation, and _blank
otherwise. This way, the user can search and browse documentation without new tabs opening in their browser.
showCornerIcon
Determines whether a corner icon is placed on the page. Defaults to true
. Set to false
to prevent the icon from being added to the page, e.g. when the search is being launched from a search bar or custom menu item. Note that the icon is draggable and users can slide it left to access content underneath.
searchBoxContainer
When set, adds the Community Search search box to the page inside of the given element. Expects a string CSS selector that locates a single element, e.g. #search-container
.
searchBoxPlaceholder
When searchBoxContainer
is set, this option configures the placeholder text inside of the search box.
colorScheme
By default, Community Search tries to match the light/dark color scheme on the page it’s embedded on, or the media query preference of the user. However, since some documentation is only available in light or dark mode, it is possible to fix the color scheme used to the widget. To do so, set this value to light
or dark
.
window.CommunitySearch API
The CommunitySearch
object has a simple API that can used to control the widget.
toggleWidget
Opens or closes the widget based on the current state. Use toggleWidget
to launch Community Search from any interaction on the page, e.g. clicking on a custom DOM element:
document.querySelector("#open-community-search").addEventListener("click", function() {
window.CommunitySearch.toggleWidget();
});
Embedding the search inside of a page
This section describes how to embed the entire search experience - search bar and results - inline into a web page. This is ideal for situations where there is an existing /search
page where you want to replace the current search with Community Search.
Coming soon 🚧
4. Standalone search page
Each search also comes with a standalone search page. It’s fairly basic right now, but it can be used as a fallback destination when the search cannot be embedded in a specific location or isn’t yet. You’ll be given the URL to your standalone page by the Orbit team.
Here’s the standalone page for the Orbit Community Search.
5. Trust & safety
If content doesn’t belong in your community, it doesn’t belong in your search. When content violates community guidelines, we want to ensure that it doesn’t appear in the search. That includes both spam and hateful/otherwise unacceptable content. We provide two ways to moderate what appears in the search - manual and automatic.
Manual Moderation
Manual moderation is available to all Community Search users. Manual moderation can be used to instantly remove any conversation from the search. The controls are available inside of your Orbit workspace.
Activities can be hidden, which will hide the entire conversation that the activity takes place in. Hidden activities can be reviewed and un-hidden in the case of a mistake.
Automated Moderation
Automated moderation is AI-powered and available to paying Community Search users. When automated moderation is enabled, each new activity is scanned for the potential to be spam, hateful, or otherwise in violation of community guidelines. If the activity is in violation, it is immediately hidden. Hidden activities can be reviewed inside of the Orbit application and un-hidden in the case of a wrong decision.
Disclaimer: As this feature uses AI, the results aren’t guaranteed to be perfect or as capable of nuance as a human community manager.
6. Advanced Features
Advanced features use AI and are available to paying Community Search users. They come in two flavors:
- boosting the best knowledge to the top of the search
- taking action with the results
Boosting knowledge
As communities get larger, they create more information, but not all of that information is actual knowledge. Generally, community members and product users are using your search to get answers to questions, get educated on certain topics, or see who is talking about what and who they could go to for help. Because of this, it’s important that the search prioritize authoritative sources and trustworthy knowledge and not just anything in the flow of information.
Community Search has several techniques to improve both the ranking and the display of search results based on signals about what is in the content and who is creating it. A few examples:
- Authority - Community Search builds on data from your Orbit workspace, so it knows which members are teammates and the members in the top Orbit Levels: your Advocates and Contributors. Content written by these individuals is given higher precedence than by others.
- Trustworthy Answers - Using AI, we analyze each conversation and determine if the primary(s) question have been answered, and which answers are the most trustworthy and contain the highest quality information. Conversations with trustworthy answers about the user’s query intention are delivered first.
Taking action with the results
These features allow users, including you, to do more with the conversations that you find via the search.
Sharing conversations
Users can share any conversation they find in the search with others. They can do this by opening the conversation menu and choosing the Open in New Tab or Copy Link options. Note: Sharing is available on all plans. Using a custom domain or subdomain for the conversation pages is available on paid plans.
Here’s an example of a shared conversation page from the Orbit Community about medals and Discord roles.
Translate content into 20+ languages
Users can translate any conversation into one of 20+ languages, message by message and in real-time, preserving the structure of the original conversation. The text can then be easily copied and pasted into other tools. Very useful for communities working in multiple languages.
Summarizing conversations into TL;DR
Some community conversations can number in the dozens or hundreds of messages. That makes it very tedious and time-consuming to catch up on the thread, but not doing so means you might miss critical information. Thankfully, Community Search can summarize conversations for you and your users, right from the conversation menu.
Here’s an example summary of a TL;DR for a conversation that took place on a Discourse:
AI Disclaimer
AI Disclaimer: Please be aware that the usage of AI in Community Search is not activated by default. If you choose to enable it, any data that is processed by AI models is strictly used for the purpose of enhancing the search experience and is neither saved nor utilized for the purpose of training AI models. We are committed to maintaining high standards of data protection and privacy.
FAQ
Do I have to pay for Community Search?
No, the basic version of Community Search is free! This includes a search for up to 3 documentation + community sources. The search can be embedded in as many places that you like, including the standalone search page. This also includes manual content moderation. If you would additional AI features including automatic content moderation / translation / summarization, as well as more sources for your search, you’d be a great fit for one of our premium plans. If that interests you, get in touch.
Can I use Community Search to add or replace a search bar?
Yes! To add a search bar to a page, use the searchBoxContainer
option described above. To replace or “take over” a search bar, you can listen for click events on the search bar and open Community Search instead. This is a good option when you don’t want to change the appearance of the search bar. Here’s a example:
document.querySelector("#search-box").addEventListener("click", function() {
window.CommunitySearch.toggleWidget();
});
How does Community Search rank search results?
For documentation results, we look at the best textual match, starting in headings and working our way down into the content. For example, a search for “authentication” will first match a page with an h1 containing the word “authentication”. Lower results will include the word “authentication” inside of smaller headers like h2, h3, h4, h5, and eventually inside of paragraph tags or general text.
For conversation results, we look at the best textual match and sort the results by date. Textual matches in the original post count for more than matches in the replies and conversations with more recent activity appear above conversations with older activity.
These ranking strategies apply to all Community Search users. On top of that, paying Community Search users also benefit from the ranking enhancements described in the Advanced Features section above.
How do I get started?
To get started with Community Search, please email us at [email protected]. Provide us with information about your workspace, any exceptions you don't want to be part of the search, and any documentation sites you'd like included. We'll then provision your search and provide you with a link to your widget. Once you've tested and are satisfied with the search, you can deploy it anywhere you need. Please note that a self-service option and self-serve management controls are coming early next year. Thank you!
- Community Search
- Step-by-Step Guide
- 1. Provision your search
- Supported conversational data sources
- Supported doc & reference data sources
- 2. Choose where to deploy the search
- Product Documentation
- Inside Your Application
- Web Site / Marketing Site / Blog
- Developer Portal / Community Site / Community Forum
- Discord Bot / Slack Bot
- 3. Embedding the widget
- Get the Code
- window.CommunitySearch options
- window.CommunitySearch API
- Embedding the search inside of a page
- 4. Standalone search page
- 5. Trust & safety
- Manual Moderation
- Automated Moderation
- 6. Advanced Features
- Boosting knowledge
- Taking action with the results
- AI Disclaimer
- FAQ
- Do I have to pay for Community Search?
- Can I use Community Search to add or replace a search bar?
- How does Community Search rank search results?
- How do I get started?