Source Transformation

Scenario

In this guide, we'll explore how to customize the display of source information. This includes modifying source icons, titles, URLs, breadcrumbs, the tabs where search results appear, and other metadata for search results and chat references.

Type Signature

The transformSource function is defined in the InkeepBaseSettings interface and allows you to modify how source information appears in different contexts:

Parameter	Type	Description
`source`	`SourceItem`	The original source data containing title, URL, description, etc.
`type`	`'chatSourceItem' \| 'searchResultItem' \| 'intelligentFormSource'`	Context where the source is being displayed
`opts`	`{ organizationDisplayName?: string; tabs?: (string \| SearchTab)[] }`	Additional options including organization name and configured tabs

The function should return a TransformedSource object that defines how the source should be displayed. This gives you control over:

Title and description formatting
URL modifications and parameters
Breadcrumb trails
Tab categorization
Icons and visual elements
Link behavior (new tab vs same window)
Additional metadata and tags

Common use cases include:

Adding organization branding to titles
Truncating long descriptions
Categorizing content into tabs
Adding tracking parameters to URLs
Customizing navigation behavior
Setting context-specific icons

type TransformSource = (
  source: SourceItem,
  type: TransformSourceType,
  opts?: TransformSourceOptions
) => TransformedSource;

interface SourceItem {
  id?: string;
  title: string | undefined;
  url: string;
  description: string | undefined;
  breadcrumbs: string[];
  type: `${SourceItemType}`;
  contentType?: string;
  tag?: string;
  tabs?: (SourceTab | string)[];
}

interface TransformedSource {
  id?: string;
  title: string;
  url: string;
  description?: string;
  breadcrumbs?: string[];
  tabs?: (string | [string, { breadcrumbs: string[] }])[];
  icon: InkeepCustomIcon;
  shouldOpenInNewTab?: boolean;
  appendToUrl?: object;
  type: string;
  tag?: string;
}

Examples

Basic source transformation

This example sets the title of all sources to include the organization name, and uses the book icon for all sources.

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => ({
    ...source,
    title: `${source.title} - My Site`,
    icon: { builtIn: "LuBookOpen" },
  }),
};

Advanced source transformation

This example shows how to transform the source data based on whether the source is a search result or a chat source.

// Advanced source transformation
const enterpriseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type, opts) => {
    // Transform based on source type
    if (type === "searchResultItem") {
      return {
        ...source,
        title: `${opts?.organizationDisplayName} - ${source.title}`,
        description: source.description?.slice(0, 150) + "...",
        breadcrumbs: [...(source.breadcrumbs || []), "Documentation"],
        tabs: ["Docs", ["API", { breadcrumbs: ["API", "Reference"] }]],
        icon: { builtIn: "LuBookOpen" },
        shouldOpenInNewTab: true,
        appendToUrl: { source: type },
      };
    }

    // Different transformation for chat sources
    if (type === "chatSourceItem") {
      return {
        ...source,
        icon: { custom: "https://assets.example.com/chat-icon.svg" },
        shouldOpenInNewTab: false,
      };
    }

    return source;
  },
};

Add a documentation tab

Let's have a "Documentation" tab that shows the sources that come from your docs. Assuming you have other sources aside docs.

You first want to define a Documentation tab:

const searchSettings: InkeepSearchSettings = {
  // ...
  tabs: ["Documentation", ...otherTabs],
};

More info on tabs can be found in the Search and Chat guide.

Then you'd need to update the transformSource function to add qualifying sources to the Documentation tab:

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => {
    const tabs = source.tabs || [];
    // Do desired check here
    if (source.type === "documentation" || source.url.includes("mydocs.com")) {
      tabs.push("Documentation");
    }
    return {
      ...source,
      tabs,
    };
  },
};

Say you're in a Blog tab, and a blog post has a breadcrumb of Blog > Announcement > My Post. You may want to hide the Blog breadcrumb when the user is in the Blog tab.

Well when setting a tab for a source, you can also decide the breadcrumbs to show in that tab for that source.

// Basic source transformation
const baseSettings: InkeepBaseSettings = {
  // ...
  transformSource: (source, type) => ({
    ...source,
    tabs: [
      [
        "Blog",
        {
          breadcrumbs:
            source.breadcrumbs[0] === "Blog"
              ? source.breadcrumbs.slice(1)
              : source.breadcrumbs,
        },
      ],
      ...otherTabs,
    ],
  }),
};