Copy page

Configuration

Search

Dev Portal offers search functionality that enhances user experience by enabling content discovery across your site. When configured, a search bar will appear in the header, allowing users to quickly find relevant information on any page.

We currently support three search providers:

• Pagefind
• Algolia DocSearch
• Inkeep

Pagefind

Pagefind is a lightweight, static search library that can be used to add search to your Dev Portal site without any external services.

To enable pagefind search, configure the search option in your configuration:

Code
{
  search: {
    type: "pagefind",
    // Optional: Maximum number of sub results per page
    maxSubResults: 3,
    // Optional: Configure search result ranking (defaults shown below)
    ranking: {
      termFrequency: 0.8,
      pageLength: 0.6,
      termSimilarity: 1.2,
      termSaturation: 1.2,
    },
  }
}

Transforming/Filtering Search Results

You can transform or filter search results using the transformResults option. This function receives the search result along with the current auth state and context, allowing you to:

• Filter results based on user permissions
• Modify result content
• Add custom results

The type of result is the same as the type returned by Pagefind's search API.

Code
{
  search: {
    type: "pagefind",
    transformResults: ({ result, auth, context }) => {
      // Return false to filter out the result
      if (!auth.isAuthenticated) return false;

      // Return true or undefined to keep the original result
      if (result.url.includes("/private/")) return true;

      // Return a modified result
      return {
        ...result,
        title: `${result.title} (${context.meta.title})`
      };
    }
  }
}

For more information about how Pagefind's ranking system works and how to customize it for your content, see the Pagefind ranking documentation.

Algolia DocSearch

Algolia DocSearch is a free search solution for open-source documentation sites. You can apply for the free DocSearch program or use your own Algolia account.

Installation

Code
npm install @zudoku/plugin-search-algolia

Configuration

Import the plugin and add it to the plugins array in your Dev Portal configuration:

Code
import { algoliaSearchPlugin } from "@zudoku/plugin-search-algolia";

const config = {
  plugins: [
    algoliaSearchPlugin({
      appId: "YOUR_APP_ID",
      apiKey: "YOUR_SEARCH_API_KEY",
      indices: ["YOUR_INDEX_NAME"],
    }),
  ],
};

You can get your credentials by applying for DocSearch or creating an index through the Algolia dashboard.

Any additional DocSearch options can be passed alongside the required fields.

Inkeep

Inkeep is an AI-powered search and chat platform that can index your documentation and provide intelligent search capabilities to your users.

Setting up Inkeep Integration

Before you can use Inkeep search in your Dev Portal site, you need to set up an Inkeep integration and have your site indexed. Here's how to get started:

1. Create an Inkeep Account

1. Go to Inkeep and sign up for an account
2. Navigate to the Inkeep Portal

2. Set up Site Indexing

1. In the Inkeep Portal, create a new project or integration
2. Configure your site URL so Inkeep can crawl and index your documentation
3. Ensure your Dev Portal site is deployed and publicly accessible for indexing
4. Wait for Inkeep to crawl and index your site content (this may take some time)

3. Get Your Integration Credentials

To add Inkeep search to your site you will need to copy some variables from your Inkeep account setting:

• API Key
• Integration ID
• Organization ID

4. Configure Dev Portal

Once you have your credentials and your site is indexed, you can configure the search option in your Dev Portal Configuration:

Code
{
  // ...
  search: {
    type: "inkeep",
    apiKey: "<your-api-key>",
    integrationId: "<your-integration-id>",
    organizationId: "<your-organization-id>",
    primaryBrandColor: "#26D6FF",
    organizationDisplayName: "Your Organization Name",
  }
  // ...
}

Customizing Inkeep

Any other base settings can be set alongside the required fields, for example filters to scope results or transformSource to customize how sources are displayed.

You can also pass searchSettings, aiChatSettings, and modalSettings to customize the respective parts of the search experience. They are merged with Zudoku's defaults and passed through to Inkeep as-is, so any option Inkeep supports can be used — including ones added after this Dev Portal version was released.

Dev Portal owns the search modal's open state, so modalSettings.isOpen is managed for you. The ⌘+K / Ctrl+K shortcut is handled by Zudoku's search button as well, which is why Inkeep's own shortcutKey is disabled by default. Setting it adds an additional shortcut rather than replacing it.

For example, to categorize results into tabs based on their URL:

Code
{
  // ...
  search: {
    type: "inkeep",
    // ...required fields from above
    transformSource: (source) => {
      if (!source.url.includes("/blog/")) return source;
      return { ...source, tabs: [...(source.tabs ?? []), "Blog"] };
    },
    searchSettings: {
      tabs: [["All", { isAlwaysVisible: true }], "Blog"],
    },
    aiChatSettings: {
      aiAssistantName: "My Assistant",
    },
  },
  // ...
}