Index API overview content for search

AGENTS.md

@@ -271,7 +271,11 @@ Since "Guides" is a Knock feature name, we should avoid using the word "guides"
 
 ## Images
 
-Images should always use Image component, rounded-md, mx-auto, border, border-gray-200.
+Images should always use the `Image` component from `lib/mdxComponents.tsx`. The component automatically applies `rounded-md`, `border`, and `border-gray-200` styling — do not add these classes manually in `className`.
+
+- Use `className="mx-auto"` to center images.
+- Use `border={false}` to disable the default border (e.g. for logos or badges).
+- When wrapping an image in a `<figure>` tag, add `className="text-center"` to the `<figure>` for `mx-auto` centering to work (the Image wrapper uses `inline-block`).
 
 ## List formatting with bold introductory text
 

components/ui/Attributes.tsx

@@ -1,3 +1,5 @@
+import { useState } from "react";
+import { motion } from "framer-motion";
 import { PropertyRow } from "./ApiReference/SchemaProperties/PropertyRow";
 
 const Attributes = ({ children }) => {
@@ -11,6 +13,9 @@ type Props = {
   typeSlug?: string;
   nameSlug?: string;
   isRequired?: boolean;
+  /** When provided, shows a "Show X" / "Hide X" toggle and renders children in a collapsible section. */
+  expandLabel?: string;
+  children?: React.ReactNode;
 };
 
 const Attribute = ({
@@ -19,18 +24,46 @@ const Attribute = ({
   description,
   typeSlug,
   isRequired,
+  expandLabel,
+  children,
 }: Props) => {
+  const [isOpen, setIsOpen] = useState(false);
+  const hasNested = !!expandLabel && !!children;
+
   return (
     <PropertyRow.Container>
       <PropertyRow.Header>
         <PropertyRow.Name>{name}</PropertyRow.Name>
-        {/* Pass an optional `typeSlug` to link the `type` to its definition in the docs*/}
+        {/* Pass an optional `typeSlug` to link the `type` to its definition in the docs */}
         {type && <PropertyRow.Type href={typeSlug}>{type}</PropertyRow.Type>}
         {isRequired && <PropertyRow.Required />}
       </PropertyRow.Header>
       {description && (
         <PropertyRow.Description>{description}</PropertyRow.Description>
       )}
+      {hasNested && (
+        <>
+          <PropertyRow.ExpandableButton
+            isOpen={isOpen}
+            onClick={() => setIsOpen(!isOpen)}
+          >
+            {isOpen ? `Hide ${expandLabel}` : `Show ${expandLabel}`}
+          </PropertyRow.ExpandableButton>
+          <motion.div
+            initial={false}
+            animate={{
+              height: isOpen ? "auto" : 0,
+              opacity: isOpen ? 1 : 0,
+              visibility: isOpen ? "visible" : "hidden",
+            }}
+            transition={{ duration: 0.2 }}
+          >
+            <PropertyRow.ChildProperties>
+              {children}
+            </PropertyRow.ChildProperties>
+          </motion.div>
+        </>
+      )}
     </PropertyRow.Container>
   );
 };

components/ui/Autocomplete.tsx

@@ -29,7 +29,7 @@ import { MenuItem } from "@telegraph/menu";
 import { Tag } from "@telegraph/tag";
 import { Code, Text } from "@telegraph/typography";
 
-import { DocsSearchItem, EndpointSearchItem } from "@/types";
+import { EnhancedDocsSearchItem, EndpointSearchItem } from "@/types";
 
 import { useInkeepModal } from "../AiChatButton";
 import { useAskAi } from "../AskAiContext";
@@ -62,7 +62,9 @@ function createAskAiPrompt(query: string): string {
   return `Can you tell me about ${query}`;
 }
 
-type ResultItem = (DocsSearchItem & BaseItem) | (EndpointSearchItem & BaseItem);
+type ResultItem =
+  | (EnhancedDocsSearchItem & BaseItem)
+  | (EndpointSearchItem & BaseItem);
 
 const algoliaAppId = process.env.NEXT_PUBLIC_ALGOLIA_APP_ID || "";
 const algoliaSearchApiKey =
@@ -193,7 +195,7 @@ const DocsSearchResult = ({
         )}
       </Text>
       <Text as="span" size="1" color="gray" weight="regular">
-        {item.section}
+        {item.pageTitle ? `${item.pageTitle as string} •` : ""} {item.section}
       </Text>
     </Box>
   );
@@ -400,7 +402,7 @@ const Autocomplete = () => {
                   ],
                   transformResponse({ hits: hitsArray }) {
                     const hits = hitsArray as (
-                      | DocsSearchItem[]
+                      | EnhancedDocsSearchItem[]
                       | EndpointSearchItem[]
                     )[];
                     // Add the "Ask AI" item at the top of the results
@@ -823,7 +825,7 @@ const Autocomplete = () => {
                                   />
                                 ) : (
                                   <DocsSearchResult
-                                    item={item as DocsSearchItem}
+                                    item={item as EnhancedDocsSearchItem}
                                     onClick={() => autocomplete.setQuery("")}
                                   />
                                 )}

components/ui/Callout.tsx

@@ -9,7 +9,8 @@ type CalloutType =
   | "alert"
   | "enterprise"
   | "beta"
-  | "roadmap";
+  | "roadmap"
+  | "community_sourced";
 
 const TYPE_CONFIG: Record<
   CalloutType,
@@ -24,6 +25,26 @@ const TYPE_CONFIG: Record<
   enterprise: { emoji: "🏢", bgColor: "blue" },
   beta: { emoji: "🚧", bgColor: "yellow" },
   roadmap: { emoji: "🛣", bgColor: "default" },
+  community_sourced: { emoji: "🤝", bgColor: "default" },
+};
+
+const COMMUNITY_SOURCED = {
+  title: "Community-sourced.",
+  text: (
+    <>
+      This tutorial is based on a real Knock implementation and may reflect
+      preferences of the original developer. If you spot something that could be
+      improved, we welcome{" "}
+      <a href="https://github.com/knocklabs/docs/" target="_blank">
+        contributions
+      </a>
+      . Join our{" "}
+      <a href="https://knock.app/join-slack" target="_blank">
+        community Slack
+      </a>{" "}
+      to discuss this implementation or share your own.
+    </>
+  ),
 };
 
 export const Callout = ({
@@ -60,6 +81,17 @@ export const Callout = ({
     ? TYPE_CONFIG[effectiveType]?.bgColor ?? customBgColor ?? "default"
     : customBgColor || "default";
 
+  const effectiveTitle =
+    title ??
+    (effectiveType === "community_sourced"
+      ? COMMUNITY_SOURCED.title
+      : undefined);
+  const effectiveText =
+    text ??
+    (effectiveType === "community_sourced"
+      ? COMMUNITY_SOURCED.text
+      : undefined);
+
   // Ensure emoji is always a string
   const emojiString = typeof emoji === "string" ? emoji : String(emoji || "💡");
   const centeredProps: TgphComponentProps<typeof Stack> = isCentered
@@ -119,17 +151,17 @@ export const Callout = ({
         py="1"
         style={{ marginBottom: "0px", color: "var(--tgph-gray-12)" }}
       >
-        {title && (
+        {effectiveTitle && (
           <Text
             as="span"
             size="2"
             weight="semi-bold"
             style={{ color: "var(--tgph-gray-12)" }}
           >
-            {title}{" "}
+            {effectiveTitle}{" "}
           </Text>
         )}
-        {text && text}
+        {effectiveText && effectiveText}
       </Text>
     </Stack>
   );

components/ui/CodeBlock.tsx

@@ -14,6 +14,7 @@ import yaml from "react-syntax-highlighter/dist/cjs/languages/hljs/yaml";
 import kotlin from "react-syntax-highlighter/dist/cjs/languages/hljs/kotlin";
 import swift from "react-syntax-highlighter/dist/cjs/languages/hljs/swift";
 import bash from "react-syntax-highlighter/dist/cjs/languages/hljs/bash";
+import xml from "react-syntax-highlighter/dist/cjs/languages/hljs/xml";
 import { useClipboard } from "@/hooks/useClipboard";
 import { useTheme } from "@/components/theme/ThemeProvider";
 
@@ -44,6 +45,9 @@ SyntaxHighlighter.registerLanguage("yaml", yaml);
 SyntaxHighlighter.registerLanguage("curl", bash);
 SyntaxHighlighter.registerLanguage("swift", swift);
 SyntaxHighlighter.registerLanguage("kotlin", kotlin);
+SyntaxHighlighter.registerLanguage("xml", xml);
+SyntaxHighlighter.registerLanguage("mjml", xml);
+SyntaxHighlighter.registerLanguage("vue", xml);
 
 export type SupportedLanguage =
   | "javascript"
@@ -186,7 +190,7 @@ export const CodeBlock: React.FC<Props> = ({
       <Stack
         bg="gray-2"
         borderBottom="px"
-        borderColor="gray-2"
+        borderColor="gray-4"
         p="2"
         alignItems="center"
       >

components/ui/CollapsibleNavItem.tsx

@@ -15,6 +15,7 @@ export type CollapsibleNavItemProps = TgphComponentProps<typeof MenuItem> & {
   className?: string;
   color?: "default" | "gray";
   isBeta?: boolean;
+  isLegacy?: boolean;
 };
 
 export const CollapsibleNavItem = ({
@@ -25,6 +26,7 @@ export const CollapsibleNavItem = ({
   color = "default",
   className = "",
   isBeta = false,
+  isLegacy = false,
   ...props
 }: CollapsibleNavItemProps) => {
   return (
@@ -52,6 +54,11 @@ export const CollapsibleNavItem = ({
               Beta
             </Tag>
           )}
+          {isLegacy && (
+            <Tag size="0" color="yellow" ml="2">
+              Legacy
+            </Tag>
+          )}
           <Icon
             icon={ChevronRight}
             size="1"

components/ui/Icons.tsx

@@ -1,5 +1,6 @@
 import {
   BookUp,
+  Cable,
   CodeXml,
   CircleHelp,
   Rows3,
@@ -14,10 +15,15 @@ import {
   Terminal,
   Landmark,
   Infinity,
+  RadioTower,
+  Rss,
   Unplug,
   Code,
   ChevronsLeftRightEllipsis,
   Package,
+  Sparkles,
+  Workflow,
+  Plug,
 } from "lucide-react";
 import {
   FaNodeJs,
@@ -159,10 +165,16 @@ const PascalCaseIcons = {
   Terminal,
   Landmark,
   Infinity,
+  RadioTower,
+  Rss,
   Unplug,
+  Cable,
   Code,
   ChevronsLeftRightEllipsis,
   Package,
+  Sparkles,
+  Workflow,
+  Plug,
 };
 
 export const Icons = Object.entries(PascalCaseIcons).reduce(

components/ui/Page.tsx

@@ -1,11 +1,11 @@
-import { createContext, useContext, useRef, useState } from "react";
-import Link from "next/link";
 import { ChevronLeft, ChevronRight } from "lucide-react";
+import Link from "next/link";
+import { createContext, useContext, useRef, useState } from "react";
 
 import { Button } from "@telegraph/button";
 import { Icon } from "@telegraph/icon";
 import { Box, Stack } from "@telegraph/layout";
-import { Text, Heading } from "@telegraph/typography";
+import { Heading, Text } from "@telegraph/typography";
 
 import { AskAiContext } from "../AskAiContext";
 import { Breadcrumbs } from "./Breadcrumbs";

components/ui/Page/Sidebar.tsx

@@ -1,26 +1,25 @@
 import { SidebarContent, SidebarSection } from "@/data/types";
-import { Box } from "@telegraph/layout";
-import { Stack } from "@telegraph/layout";
-import { NavItem } from "../NavItem";
 import { debounce } from "@/lib/debounce";
+import { TgphComponentProps } from "@telegraph/helpers";
+import { Box, Stack } from "@telegraph/layout";
+import { Tag } from "@telegraph/tag";
 import { useRouter } from "next/router";
+import { createContext, useContext, useEffect, useState } from "react";
 import {
   CollapsibleNavItem,
   type CollapsibleNavItemProps,
 } from "../CollapsibleNavItem";
-import { useState, useEffect, createContext, useContext } from "react";
+import { NavItem } from "../NavItem";
+import { usePageContext } from "../Page";
 import {
-  isPathTheSame,
   highlightResource,
+  isPathTheSame,
   stripPrefix,
   updateNavStyles,
-  useIsPageReady,
   useHighlightedPath,
+  useIsPageReady,
 } from "./helpers";
-import { Tag } from "@telegraph/tag";
 import { ScrollerBottomGradient } from "./ScrollerBottomGradient";
-import { usePageContext } from "../Page";
-import { TgphComponentProps } from "@telegraph/helpers";
 
 interface SidebarContextType {
   samePageRouting: boolean;
@@ -178,6 +177,7 @@ const ItemWithSubpages = ({
       {...depthAdjustedCollapsibleNavItemProps}
       label={section.title ?? section.slug}
       isBeta={section?.isBeta}
+      isLegacy={section?.isLegacy}
       isOpen={isOpen}
       setIsOpen={setIsOpen}
     >
@@ -205,6 +205,11 @@ const ItemWithSubpages = ({
                   Beta
                 </Tag>
               )}
+              {page.isLegacy && (
+                <Tag color="yellow" ml="2" size="0">
+                  Legacy
+                </Tag>
+              )}
             </NavItem>
           </Box>
         );
@@ -248,6 +253,11 @@ const Item = ({ section, preSlug = "", depth = 0, defaultOpen }: ItemProps) => {
           Beta
         </Tag>
       )}
+      {section.isLegacy && (
+        <Tag color="yellow" ml="2" size="0">
+          Legacy
+        </Tag>
+      )}
     </NavItem>
   );
 };