@eventcatalog/core 3.35.0 → 3.36.1

package/dist/docs/development/customization/01-customize-landing-page.md

@@ -0,0 +1,155 @@
+---
+sidebar_position: 2
+keywords:
+- EventCatalog landing page
+sidebar_label: Custom landing page
+title: Customize landing page
+description: Customize landing pages in EventCatalog
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="2.37.1" />
+
+EventCatalog provides a landing page for your catalog, this is the first page that users see when they visit your catalog. See the demo [here](https://demo.eventcatalog.dev/).
+
+You can customize the landing page with your own content, HTML and EventCatalog components.
+
+:::info 
+Landing page customization is only available for customers on [paid plans](https://www.eventcatalog.dev/pricing). You can get a 14 day free trial of EventCatalog Starter Plan on [EventCatalog Cloud](https://eventcatalog.cloud).
+:::
+
+### Example of a custom landing page
+
+You can add any HTML you want to your landing page, in this example we have added custom content using EventCatalog components, which includes the
+visualizer for a domains, subdomains and flows.
+
+<div className="space-y-2 text-center mb-8">
+<img src="/img/landing-page-example.png" alt="EventCatalog Custom Landing Page" className="rounded-lg mb-0" />
+<a href="https://demo.eventcatalog.dev" className="block p-0 m-0">View custom landing page demo</a>
+</div>
+
+## How to customize your landing page
+
+1. Setup and configure your [EventCatalog Starter or Scale License key](/docs/development/getting-started/configuration-overview#configuring-environment-variables).
+    - You can get a 14 day free trial of EventCatalog Starter Plan on [EventCatalog Cloud](https://eventcatalog.cloud).
+1. Create a new folder called `pages` and an Astro file called `homepage.astro`
+    - Example: `/pages/homepage.astro`
+1. Add the contents to your Astro file.
+    - You can see a full example of this on our [GitHub repository](https://github.com/event-catalog/eventcatalog/blob/main/examples/default/pages/homepage.astro).
+1. Run `npm run dev` or `npm run build` to see your changes.
+
+:::info What is Astro?
+[Astro](https://astro.build/) is a static site builder that powers EventCatalog. You can learn more about Astro [here](https://docs.astro.build/en/getting-started/).
+:::
+
+**Example of homepage.astro**
+
+```md title="/pages/homepage.astro"
+---
+# Import EventCatalog components to use in your landing page
+const { Tile, Tiles, Flow, NodeGraph, Admonition } = Astro.props.components;
+---
+
+<div class="p-8 pt-2 max-w-8xl mx-auto">
+  <h1 class="text-4xl font-bold text-gray-800 mb-4">Welcome to FlowMart's EventCatalog</h1>
+  <p class="text-lg text-gray-600 mb-8">Explore the events, services, and domains that power the FlowMart ecosystem. This catalog provides a centralized place to discover and understand our asynchronous architecture.</p>
+
+  <Admonition type="info" title="Demo application">
+    <p>This is a demo of the EventCatalog and what it can do. The company is called FlowMart and they are an e-commerce company.</p>
+    <p>Using EventCatalog, we documented their systems (domains, services, events, commands, flows) and how they fit together.</p>
+  </Admonition>
+
+  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8 pt-4">
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">E-Commerce Domain</h2>
+      <p class="text-gray-500 mb-2">The core domain of FlowMart, responsible for all e-commerce operations.</p>
+      <NodeGraph id="E-Commerce" version="1.0.0" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Orders Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all orders.</p>
+      <NodeGraph id="Orders" version="0.0.3" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all payments.</p>
+      <NodeGraph id="Payment" version="0.0.1" type="domain" />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Subscription Domain</h2>
+      <p class="text-gray-500 mb-2">The sub-domain responsible for all subscriptions.</p>
+      <NodeGraph id="Subscription" version="0.0.1" type="domain" />
+    </div>
+  </div>
+
+  <div class="bg-blue-50 p-6 rounded-lg shadow-md mb-12">
+    <h2 class="text-2xl font-semibold text-blue-800 mb-3">Discover Our Architecture</h2>
+    <p class="text-gray-700 mb-4">
+      Navigate through our Domains to understand the different business capabilities, explore Services to see the microservices involved, and dive into Events and Commands to see how they communicate.
+    </p>
+    <p class="text-gray-700">
+      Use the search bar above or browse the sections in the sidebar to get started.
+    </p>
+  </div>
+
+  <div class="grid grid-cols-2 gap-4 border-b border-gray-200 pb-8">
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Cancel Subscription Flow</h2>
+      <p class="text-gray-500 mb-2">This flow is triggered when a user cancels their subscription.</p>
+      <Flow id="CancelSubscription" version="latest" includeKey={false} />
+    </div>
+    <div class="col-span-1">
+      <h2 class="text-2xl font-semibold text-gray-700 mb-2">Payment Flow</h2>
+      <p class="text-gray-500 mb-2">This flow documents how a payment is processed at FlowMart.</p>
+      <Flow id="PaymentFlow" version="latest" includeKey={false} />
+    </div>
+  </div>
+
+  <div class="border-b border-gray-200 pb-8 py-4">
+    <h2 class="text-3xl font-semibold text-gray-700 py-4">Quick Links</h2>
+    <p class="text-gray-700 mb-4">Learn how to get started with EventCatalog, create domains, services, events, and commands.</p>
+    <Tiles columns={3}>
+      <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
+      <Tile icon="RectangleGroupIcon" href="https://eventcatalog.dev/docs/development/guides/domains/creating-domains/adding-domains" title="Creating domains" description="Learn how to create domains in your event catalog" />
+      <Tile icon="ServerIcon" href="https://eventcatalog.dev/docs/development/guides/services/adding-services" title="Creating services" description="Learn how to create services in your event catalog" />
+      <Tile icon="ChatBubbleLeftIcon" iconColor="text-blue-500" href="https://eventcatalog.dev/docs/development/guides/messages/commands/introduction" title="Creating commands" description="Learn how to create commands in your event catalog" />
+      <Tile icon="BoltIcon" iconColor="text-orange-500" href="https://eventcatalog.dev/docs/development/guides/messages/events/introduction" title="Creating events" description="Learn how to create events in your event catalog" />
+      <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/docs/owners" title="Assigning owners to resources" description="Learn how to assign owners to resources in your event catalog" />
+    </Tiles>
+  </div>
+
+  <div class="pb-8 py-4">
+    <h2 class="text-3xl font-semibold text-gray-700 mb-6 pt-4">Join the community</h2>
+
+    <p class="text-gray-700 mb-4">Our project and community is growing fast. We have over 1000+ members in our <a href="https://eventcatalog.dev/discord" class="text-blue-500 hover:text-blue-600">Discord community</a>.</p>
+
+    <Tiles columns={2}>
+      <Tile icon="UserGroupIcon" iconColor="text-green-500" href="https://eventcatalog.dev/discord" title="Join the Discord community" description="Join the community to get help and support" />
+      <Tile icon="StarIcon"  iconColor="text-yellow-500" href="https://github.com/event-catalog/eventcatalog/stargazers" title="Star EventCatalog on GitHub" description="If you like the project, please star it on GitHub to show your support ❤️" />
+    </Tiles>
+  </div>
+
+</div>
+
+
+```
+
+See the example output [here](https://demo.eventcatalog.dev)
+
+
+### Using components
+
+You can use EventCatalog components in your custom landing page.
+
+These include embedding visuals, flows, and more.
+
+Example:
+
+```md
+<Tiles columns={3}>
+  <Tile icon="BookOpenIcon" href="https://eventcatalog.dev/docs/development/getting-started" title="Getting started with EventCatalog" description="How to get started with EventCatalog" />
+</Tiles>
+```
+
+You can get a list of components [here](/docs/components).

package/dist/docs/development/customization/02-themes.md

@@ -0,0 +1,429 @@
+---
+keywords:
+  - EventCatalog themes
+  - dark mode
+  - light mode
+  - customization
+  - custom theme
+sidebar_label: Themes
+title: Themes
+description: Customize the look and feel of your catalog with built-in themes, dark/light mode, and custom themes
+---
+
+import PlanBanner from '@site/src/components/MDX/PlanBanner';
+
+EventCatalog comes with a selection of built-in themes and supports both light and dark modes out of the box.
+
+## Choosing a theme
+
+To set a theme, add the `theme` property to your `eventcatalog.config.js` file:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... other config
+  theme: 'sapphire',
+};
+```
+
+### Available themes
+
+EventCatalog includes the following built-in themes:
+
+| Theme | Description |
+|-------|-------------|
+| `default` | Purple accent - the original EventCatalog look |
+| `ocean` | Teal accent - calm and professional |
+| `sapphire` | Blue accent - premium enterprise feel |
+| `sunset` | Orange accent - warm and energetic |
+| `forest` | Dark green accent - natural and grounded |
+
+
+## Light and dark mode
+
+EventCatalog supports both light and dark modes. Users can toggle between modes using the theme switcher in the header.
+
+### How it works
+
+- The theme toggle appears in the header navigation
+- **System preference by default**: New visitors see light or dark mode based on their operating system preference
+- **Remembers user choice**: Once a user manually toggles the theme, their preference is saved and used on future visits
+- **Syncs across tabs**: Theme changes sync across browser tabs
+- **Responds to system changes**: If no manual preference is set, the theme automatically updates when the user changes their OS dark mode setting
+
+### Theme persistence
+
+When a user manually selects light or dark mode, their preference is stored in `localStorage` under the key `eventcatalog-theme`. This ensures their choice persists across page reloads and browser sessions.
+
+If no preference is stored, EventCatalog automatically follows the user's system preference using the `prefers-color-scheme` media query.
+
+---
+
+## Creating custom themes
+
+<PlanBanner plan="Scale" />
+
+Custom themes allow you to fully brand EventCatalog with your organization's colors. You define your theme in `eventcatalog.styles.css` using CSS variables.
+
+### Step 1: Create your theme CSS
+
+Add your custom theme to `eventcatalog.styles.css` in your project root. Your theme needs to define CSS variables for both light and dark modes.
+
+```css title="eventcatalog.styles.css"
+/**
+ * Custom "ruby" theme - Red accent colors
+ */
+
+/* Light Mode */
+:root[data-catalog-theme="ruby"],
+:root[data-catalog-theme="ruby"][data-theme="light"] {
+  /* Accent colors */
+  --ec-accent: 220 38 38;           /* red-600 */
+  --ec-accent-hover: 185 28 28;     /* red-700 */
+  --ec-accent-subtle: 254 226 226;  /* red-100 */
+  --ec-accent-text: 153 27 27;      /* red-800 */
+
+  /* Buttons */
+  --ec-button-bg: 185 28 28;        /* red-700 */
+  --ec-button-bg-hover: 153 27 27;  /* red-800 */
+  --ec-button-text: 255 255 255;
+
+  /* Sidebar */
+  --ec-sidebar-active-bg: 185 28 28;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 185 28 28;
+
+  /* You can override any CSS variable here */
+}
+
+/* Dark Mode */
+:root[data-catalog-theme="ruby"][data-theme="dark"] {
+  /* Accent colors - use lighter shades for dark mode */
+  --ec-accent: 248 113 113;         /* red-400 */
+  --ec-accent-hover: 239 68 68;     /* red-500 */
+  --ec-accent-subtle: 127 29 29 / 0.3;
+  --ec-accent-text: 252 165 165;    /* red-300 */
+
+  /* Buttons */
+  --ec-button-bg: 220 38 38;        /* red-600 */
+  --ec-button-bg-hover: 239 68 68;  /* red-500 */
+  --ec-button-text: 255 255 255;
+
+  /* Sidebar */
+  --ec-sidebar-active-bg: 220 38 38;
+  --ec-sidebar-active-text: 255 255 255;
+}
+```
+
+### Step 2: Set the theme in config
+
+Reference your custom theme name in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+export default {
+  // ... other config
+  theme: 'ruby',  // Matches data-catalog-theme="ruby" in your CSS
+};
+```
+
+### Step 3: Test both modes
+
+Start your catalog and test both light and dark modes to ensure all colors look correct:
+
+```bash
+npm run dev
+```
+
+Toggle between light and dark mode using the theme switcher in the header.
+
+:::tip Tailwind Color Reference
+Use [Tailwind CSS colors](https://tailwindcss.com/docs/customizing-colors) as a reference for your RGB values. For example, `red-600` is `220 38 38`.
+:::
+
+:::caution RGB Format Required
+CSS variables must use space-separated RGB values (e.g., `220 38 38`) **without** the `rgb()` wrapper. This allows EventCatalog to apply opacity modifiers like `rgb(var(--ec-accent) / 0.5)`.
+:::
+
+---
+
+## Full CSS variable reference
+
+Here are all available CSS variables you can customize:
+
+### Core colors
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-accent` | Primary accent color for highlights and interactive elements |
+| `--ec-accent-hover` | Accent color on hover |
+| `--ec-accent-subtle` | Light accent background (badges, highlights) |
+| `--ec-accent-text` | Text color on accent backgrounds |
+| `--ec-accent-gradient-from` | Gradient start color |
+| `--ec-accent-gradient-to` | Gradient end color |
+
+### Header
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-header-bg` | Header background |
+| `--ec-header-text` | Header text color |
+| `--ec-header-border` | Header border color |
+
+### Sidebar
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-sidebar-bg` | Sidebar background |
+| `--ec-sidebar-bg-gradient` | Sidebar gradient end color |
+| `--ec-sidebar-border` | Sidebar border |
+| `--ec-sidebar-text` | Sidebar text color |
+| `--ec-sidebar-active-bg` | Active item background |
+| `--ec-sidebar-active-text` | Active item text |
+| `--ec-sidebar-hover-bg` | Hover item background |
+
+### Rail
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-rail-bg` | Inset panel/navigation rail background, sits slightly off the page background |
+| `--ec-rail-active-bg` | Active item background within a rail |
+
+### Content area
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-content-bg` | Nested sidebar content background |
+| `--ec-content-text` | Content text |
+| `--ec-content-text-muted` | Muted text |
+| `--ec-content-text-secondary` | Secondary text |
+| `--ec-content-border` | Content borders |
+| `--ec-content-hover` | Hover background |
+| `--ec-content-active` | Active item background |
+
+### Page
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-page-bg` | Main page background |
+| `--ec-page-text` | Page text color |
+| `--ec-page-text-muted` | Muted/secondary text |
+| `--ec-page-border` | Page borders |
+
+### Buttons
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-button-bg` | Button background |
+| `--ec-button-bg-hover` | Button hover background |
+| `--ec-button-text` | Button text color |
+
+### Form inputs
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-input-bg` | Input field background |
+| `--ec-input-border` | Input field border |
+| `--ec-input-text` | Input field text |
+| `--ec-input-placeholder` | Placeholder text color |
+
+### Dropdowns
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-dropdown-bg` | Dropdown background |
+| `--ec-dropdown-text` | Dropdown text |
+| `--ec-dropdown-hover` | Dropdown hover background |
+| `--ec-dropdown-border` | Dropdown border |
+
+### Icons
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-icon-color` | Default icon color |
+| `--ec-icon-hover` | Icon hover color |
+
+### Other
+
+| Variable | Description |
+|----------|-------------|
+| `--ec-card-bg` | Card/elevated surface background |
+| `--ec-code-bg` | Code block background |
+| `--ec-group-icon-bg` | Group header icon background |
+| `--ec-group-icon-text` | Group header icon text |
+
+---
+
+## Dark mode prose overrides
+
+For custom themes, you may want to customize how markdown content (prose) appears in dark mode:
+
+```css title="eventcatalog.styles.css"
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(163 163 163);
+  --tw-prose-headings: rgb(245 245 245);
+  --tw-prose-links: rgb(248 113 113);  /* Match your accent */
+  --tw-prose-bold: rgb(245 245 245);
+  --tw-prose-code: rgb(245 245 245);
+  --tw-prose-pre-bg: rgb(23 23 23);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a {
+  color: rgb(248 113 113);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a:hover {
+  color: rgb(252 165 165);
+}
+```
+
+---
+
+## Example: Complete custom theme
+
+Here's a complete example of a custom "ruby" red theme you can use as a starting point:
+
+<details>
+<summary>View full ruby theme CSS</summary>
+
+```css title="eventcatalog.styles.css"
+/**
+ * Ruby Theme - Custom Red Theme
+ */
+
+/* Ruby Light Mode */
+:root[data-catalog-theme="ruby"],
+:root[data-catalog-theme="ruby"][data-theme="light"] {
+  --ec-header-bg: 255 255 255;
+  --ec-header-text: 23 23 23;
+  --ec-header-border: 229 229 229;
+
+  --ec-primary: 220 38 38;
+  --ec-primary-hover: 185 28 28;
+
+  --ec-accent: 220 38 38;
+  --ec-accent-hover: 185 28 28;
+  --ec-accent-subtle: 254 226 226;
+  --ec-accent-text: 153 27 27;
+  --ec-accent-gradient-from: 239 68 68;
+  --ec-accent-gradient-to: 185 28 28;
+
+  --ec-button-bg: 185 28 28;
+  --ec-button-bg-hover: 153 27 27;
+  --ec-button-text: 255 255 255;
+
+  --ec-dropdown-bg: 255 255 255;
+  --ec-dropdown-text: 64 64 64;
+  --ec-dropdown-hover: 254 242 242;
+  --ec-dropdown-border: 229 229 229;
+
+  --ec-icon-color: 82 82 82;
+  --ec-icon-hover: 185 28 28;
+
+  --ec-sidebar-bg: 255 255 255;
+  --ec-sidebar-bg-gradient: 254 242 242;
+  --ec-sidebar-border: 229 229 229;
+  --ec-sidebar-text: 82 82 82;
+  --ec-sidebar-active-bg: 185 28 28;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 185 28 28;
+
+  --ec-content-bg: 255 255 255;
+  --ec-content-text: 23 23 23;
+  --ec-content-text-muted: 82 82 82;
+  --ec-content-text-secondary: 115 115 115;
+  --ec-content-border: 229 229 229;
+  --ec-content-hover: 250 250 250;
+  --ec-content-active: 254 226 226;
+
+  --ec-input-bg: 255 255 255;
+  --ec-input-border: 212 212 212;
+  --ec-input-text: 23 23 23;
+  --ec-input-placeholder: 163 163 163;
+
+  --ec-group-icon-bg: 254 226 226;
+  --ec-group-icon-text: 153 27 27;
+
+  --ec-page-bg: 255 255 255;
+  --ec-page-text: 23 23 23;
+  --ec-page-text-muted: 82 82 82;
+  --ec-page-border: 229 229 229;
+
+  --ec-card-bg: 255 255 255;
+  --ec-code-bg: 250 250 250;
+}
+
+/* Ruby Dark Mode */
+:root[data-catalog-theme="ruby"][data-theme="dark"] {
+  --ec-header-bg: 23 23 23;
+  --ec-header-text: 245 245 245;
+  --ec-header-border: 38 38 38;
+
+  --ec-accent: 248 113 113;
+  --ec-accent-hover: 239 68 68;
+  --ec-accent-subtle: 127 29 29 / 0.3;
+  --ec-accent-text: 252 165 165;
+  --ec-accent-gradient-from: 248 113 113;
+  --ec-accent-gradient-to: 239 68 68;
+
+  --ec-button-bg: 220 38 38;
+  --ec-button-bg-hover: 239 68 68;
+  --ec-button-text: 255 255 255;
+
+  --ec-dropdown-bg: 23 23 23;
+  --ec-dropdown-text: 212 212 212;
+  --ec-dropdown-hover: 38 38 38;
+  --ec-dropdown-border: 64 64 64;
+
+  --ec-icon-color: 163 163 163;
+  --ec-icon-hover: 252 165 165;
+
+  --ec-sidebar-bg: 10 10 10;
+  --ec-sidebar-bg-gradient: 10 10 10;
+  --ec-sidebar-border: 38 38 38;
+  --ec-sidebar-text: 163 163 163;
+  --ec-sidebar-active-bg: 220 38 38;
+  --ec-sidebar-active-text: 255 255 255;
+  --ec-sidebar-hover-bg: 38 38 38;
+
+  --ec-content-bg: 10 10 10;
+  --ec-content-text: 245 245 245;
+  --ec-content-text-muted: 163 163 163;
+  --ec-content-text-secondary: 163 163 163;
+  --ec-content-border: 38 38 38;
+  --ec-content-hover: 23 23 23;
+  --ec-content-active: 38 38 38;
+
+  --ec-input-bg: 23 23 23;
+  --ec-input-border: 64 64 64;
+  --ec-input-text: 245 245 245;
+  --ec-input-placeholder: 115 115 115;
+
+  --ec-group-icon-bg: 38 38 38;
+  --ec-group-icon-text: 252 165 165;
+
+  --ec-page-bg: 10 10 10;
+  --ec-page-text: 245 245 245;
+  --ec-page-text-muted: 163 163 163;
+  --ec-page-border: 38 38 38;
+
+  --ec-card-bg: 10 10 10;
+  --ec-code-bg: 23 23 23;
+}
+
+/* Ruby theme prose overrides */
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose {
+  --tw-prose-body: rgb(163 163 163);
+  --tw-prose-headings: rgb(245 245 245);
+  --tw-prose-links: rgb(248 113 113);
+  --tw-prose-bold: rgb(245 245 245);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a {
+  color: rgb(248 113 113);
+}
+
+:root[data-catalog-theme="ruby"][data-theme="dark"] .prose a:hover {
+  color: rgb(252 165 165);
+}
+```
+
+</details>

package/dist/docs/development/customization/03-search.md

@@ -0,0 +1,79 @@
+---
+sidebar_position: 1
+keywords:
+  - EventCatalog search
+  - full-content search
+  - indexed search
+  - pagefind
+  - search configuration
+sidebar_label: Search
+title: Search
+description: Configure resource metadata search or opt-in to full-content indexed search
+---
+
+import AddedIn from '@site/src/components/MDX/AddedIn';
+
+<AddedIn version="3.36.0" />
+
+EventCatalog ships with two search modes. The default is a fast metadata search that works with no extra configuration. An opt-in indexed mode adds full-content search powered by [Pagefind](https://pagefind.app/).
+
+## Understand the modes
+
+**Resource search (default)** indexes the metadata of every catalog resource — names, summaries, badges, types, and identifiers. It is fast, requires no build step, and works in both `static` and `server` output modes.
+
+**Indexed search (opt-in)** builds a static index of the full markdown content of your catalog at build time. It can find matches inside the body of a page, changelogs, custom docs, and resource docs — not just the frontmatter fields.
+
+## Enable indexed search
+
+Set `search.type` to `'indexed'` in `eventcatalog.config.js`:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  search: {
+    type: 'indexed',
+  },
+};
+```
+
+No other changes are required. The index is built automatically as part of `eventcatalog build` and also during `eventcatalog dev`.
+
+## What gets indexed
+
+When indexed search is enabled, the following content is included in the index:
+
+- All catalog resources: events, commands, queries, services, domains, subdomains, channels, containers, data products, entities, and flows
+- Custom docs pages
+- Resource docs
+- Changelogs
+
+## When the index is built
+
+During `eventcatalog build`, the indexer runs after the Astro build and writes the index to `<outDir>/pagefind`.
+
+During `eventcatalog dev`, the index is built on startup and rebuilt automatically whenever any `.md` or `.mdx` file changes (debounced to avoid excessive rebuilds). The first build may take a few seconds depending on the size of your catalog. Subsequent incremental rebuilds are faster.
+
+## Result ranking
+
+Indexed results are ranked by relevance. Matches in the resource title and identifier score highest, followed by matches in the summary and type. Content-body matches score lower than title matches but are still surfaced when no title match is found.
+
+## Auth and the `/pagefind` assets
+
+:::warning Private catalogs
+If your catalog uses authentication (an `eventcatalog.auth.js` file is present), the generated `/pagefind` directory is served as static client-readable assets. Anyone who can load the page can download the index, which contains the full text of all indexed content.
+
+Ensure your deployment platform protects the `/pagefind` path behind the same authentication layer as the rest of your catalog.
+:::
+
+## Keep resource search
+
+To stay on the default resource search, either omit the `search` key entirely or set the type explicitly:
+
+```js title="eventcatalog.config.js"
+module.exports = {
+  search: {
+    type: 'resource', // default, no index built
+  },
+};
+```
+
+Existing catalogs are not affected by this feature — no changes are needed unless you want to opt in.