lumapps · radiuso · Jun 1, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,99 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Repository Overview
+
+This is a **documentation repository** for LumApps Customizations API (SDK and CLI). It provides technical documentation for developers who want to extend LumApps sites using JavaScript and CSS customizations.
+
+The documentation is built using **Jekyll** with the `just-the-docs` theme and is organized into markdown files under the `/docs` directory.
+
+## Documentation Structure
+
+The documentation is organized hierarchically:
+
+- **Main entry point**: [docs/index.md](docs/index.md) - Customizations API overview
+- **JavaScript API**: [docs/javascript.md](docs/javascript.md) and subdirectory [docs/javascript/](docs/javascript/)
+  - API reference: [docs/javascript/api.md](docs/javascript/api.md)
+  - Capabilities: [docs/javascript/capabilities.md](docs/javascript/capabilities.md)
+  - Best practices: [docs/javascript/best-pratices.md](docs/javascript/best-pratices.md)
+  - Development & deployment: [docs/javascript/development-and-deployment.md](docs/javascript/development-and-deployment.md)
+  - Use cases: [docs/javascript/use-cases.md](docs/javascript/use-cases.md)
+  - FAQ: [docs/javascript/faq.md](docs/javascript/faq.md)
+- **CSS API**: [docs/css.md](docs/css.md) and subdirectory [docs/css/](docs/css/)
+  - API reference: [docs/css/api.md](docs/css/api.md)
+  - Best practices: [docs/css/best-practices.md](docs/css/best-practices.md)
+  - Development & deployment: [docs/css/development-and-deployment.md](docs/css/development-and-deployment.md)
+  - Use cases: [docs/css/use-cases.md](docs/css/use-cases.md)
+
+## Jekyll Configuration
+
+The site uses Jekyll with the following configuration:
+- **Theme**: `pmarsceill/just-the-docs` (remote theme)
+- **Config file**: [docs/_config.yml](docs/_config.yml)
+- **Site title**: "LumApps Developers"
+
+All markdown files include YAML frontmatter with:
+- `layout`: typically `default`
+- `title`: page title
+- `nav_order`: controls navigation order
+- `parent` / `grand_parent`: defines hierarchical navigation
+- `has_children`: indicates if the page has child pages
+
+## Key Customizations API Concepts
+
+### JavaScript API
+The JavaScript Customizations API is based on callbacks that execute after the LumApps application loads. The main entry point is:
+
+```javascript
+window.lumapps.customize(callback, configuration)
+```
+
+The callback receives parameters including:
+- `targets` - where customizations can be placed (PAGE, HEADER, NAVIGATION, SEARCH_BOX, etc.)
+- `placement` - position relative to target (ABOVE, BELOW, LEFT, RIGHT, etc.)
+- `components` - reusable LumApps components (Message, Button, Dropdown, etc.)
+- `constants` - constant values for component configuration
+- `render` - function to render customizations
+- `session` - current user session data
+- `on` - event subscription
+- `api` - Axios instance for AJAX requests
+- `addWidgetFilters` - function to add custom filters to widgets
+- `addSearchFilters` - function to add custom filters to global search and Ask AI
+
+### CSS API
+CSS customizations allow developers to add custom styles to modify the visual appearance of LumApps sites. The API provides supported CSS classes and anchors that remain stable across releases.
+
+### Deployment Model
+Customizations are deployed by adding JavaScript/CSS code to the site's `<head>` tag through the LumApps administration UI (Style > Advanced > Head tag HTML).
+
+## Documentation Maintenance Guidelines
+
+When editing documentation:
+
+1. **Preserve frontmatter**: Always maintain the YAML frontmatter structure
+2. **Navigation hierarchy**: Keep `parent`, `grand_parent`, and `nav_order` consistent
+3. **Code examples**: Include practical JavaScript/CSS examples that demonstrate actual API usage
+4. **Security considerations**: When documenting public site features, include security warnings (especially for `shouldRenderOnPublicSites`)
+5. **Browser compatibility**: Mention browser support when relevant (LumApps supports latest 2 versions of Chrome, Firefox, Safari, Edge)
+6. **Performance impact**: Document performance considerations for customizations (recommended 2-5KB total)
+7. **API versioning**: Note when features are deprecated or breaking changes occur
+
+## Recent Updates
+
+Based on recent commits:
+- **Search filters functionality added** - New `addSearchFilters` API for global search and Ask AI
+- Widget filters functionality added to documentation
+- Public sites customization documentation added
+- MDI (Material Design Icons) documentation updated
+- New targets added to the API
+- Search extension result documentation added
+
+## When Working on This Repository
+
+- This is a **documentation-only** repository - no application code or build processes
+- Changes are typically updates to markdown files in `/docs`
+- Focus on clarity, completeness, and accurate code examples
+- Ensure all links between documentation pages are correct
+- Validate that YAML frontmatter is properly formatted
+- Keep code examples consistent with the latest API version
diff --git a/docs/javascript/api.md b/docs/javascript/api.md
@@ -17,6 +17,7 @@ The main entrypoint of this API is the object ```window.lumapps```. On this obje
 - [getInternalUrl](#getinternalurl)
 - [displayNotification](#displaynotification)
 - [addWidgetFilters](#addwidgetfilters)
+- [addSearchFilters](#addsearchfilters)
 
 ## customize
 
@@ -39,6 +40,7 @@ Where `callback` is a function that will receive a set of `parameters` and retur
 | `getLatestEvents`  | Function that retrieves the latest events generated on the application. See more details for this function [here](#getLatestEvents)                                |
 | `state`            | Object that provides state management capabilities. See more details for this function [here](#state)                                                              |
 | `addWidgetFilters` | Function that allows adding custom filters to widgets. Supports public site customizations when configured. See more details [here](#addwidgetfilters)              |
+| `addSearchFilters` | Function that allows adding custom filters to global search and Ask AI. Supports public site customizations when configured. See more details [here](#addsearchfilters) |
 | `onNavigation` (**deprecated**) | Function that will be executed once any widget in a content is rendered. See more details for this function [here](#on-widget-rendered)               |
 | `onWidgetRendered` (**deprecated**) | Function that will be executed once the application has performed a navigation. See more details for this function [here](#on-navigation)         |
 | `api`          | [Axios](https://github.com/axios/axios) instance that allows the developer to execute AJAX requests. See more details for this function [here](#axios-api)             |
@@ -1466,6 +1468,47 @@ window.lumapps.customize(({ addWidgetFilters }) => {
 
 See the [Public Site Customizations Security](#public-site-customizations-security) section for more information about enabling and using public site customizations safely.
 
+### addSearchFilters
+
+The `addSearchFilters` function allows you to add custom filters to global search and Ask AI features on your site. This function is available in two locations with different capabilities:
+
+#### Top-level function (Legacy)
+
+```js
+window.lumapps.addSearchFilters(filterConfig);
+```
+
+**Important:** The top-level `window.lumapps.addSearchFilters()` function **does not support public site customizations**. Filters added using this method will only work for authenticated users.
+
+#### Within customize callback (Recommended)
+
+```js
+window.lumapps.customize(({ addSearchFilters }) => {
+    addSearchFilters(filterConfig);
+}, { shouldRenderOnPublicSites: true });
+```
+
+**Important:** When using `addSearchFilters` within the `window.lumapps.customize` callback, the function **supports public site customizations** when the `shouldRenderOnPublicSites` configuration option is set to `true`. This allows search filters to work for both authenticated and anonymous users on public sites.
+
+**Recommendation:** Use the `addSearchFilters` function within the `customize` callback to ensure compatibility with public site customizations and future updates.
+
+```js
+// Example: Adding search filters with public site support
+window.lumapps.customize(({ addSearchFilters }) => {
+    addSearchFilters({
+        // Your filter configuration here
+    });
+}, { shouldRenderOnPublicSites: true });
+```
+
+**Use cases:**
+- Filter search results based on custom metadata or business logic
+- Apply contextual filters to Ask AI queries based on user attributes or session data
+- Restrict search results to specific content types, communities, or categories
+- Add dynamic filters based on user permissions or roles
+
+See the [Public Site Customizations Security](#public-site-customizations-security) section for more information about enabling and using public site customizations safely.
+
 ### CSS classes
 
 Our Design System provides a set of classes that can be reused in order to style our components while maintaining a visual coherence with the rest of the site. These classes can be passed in when using the `className` option for each component, or when you are using the `RawHTML` component. These CSS classes need no custom CSS, they are available out-of-the-box. If you want to implement custom CSS, please take a look at that documentation [here](../css/README.md)