Documentation
Embed Community Search
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
Within the Orbit App
In the βCS Widgetβ section of Orbit, the embed code will be displayed.
Manually
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>
By default, embedding this code 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.
Configuration Options
Below are different Javascript variables you can set to modify how the widget behaves.
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
.
Toggle the Widget via the 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();
});
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.
- Embed Community Search
- Get the Code
- Within the Orbit App
- Manually
- Configuration Options
- window.CommunitySearch options
- Toggle the Widget via the window.CommunitySearch API
- 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