feat(ai-kit): add document description override for KB docs and DocSearch result excerpts

Smart Cloud Solutions Inc. · Smart Cloud Solutions Inc. · commit 486cfc0da9e8 · 2026-04-17T19:01:57.000+02:00
diff --git a/ai-kit-admin/dist/chunks/330.4f1e5014.js b/ai-kit-admin/dist/chunks/330.4f1e5014.js
diff --git a/ai-kit-admin/dist/chunks/330.828d35e6.js b/ai-kit-admin/dist/chunks/330.828d35e6.js
diff --git a/ai-kit-admin/dist/index.asset.php b/ai-kit-admin/dist/index.asset.php
@@ -1 +1 @@
-<?php return array('dependencies' => array('jquery', 'react', 'react-dom', 'react-jsx-runtime', 'wp-components', 'wp-data', 'wp-i18n'), 'version' => 'e972fb7777808103e323');
+<?php return array('dependencies' => array('jquery', 'react', 'react-dom', 'react-jsx-runtime', 'wp-components', 'wp-data', 'wp-i18n'), 'version' => 'fb86e5d1fe3b40905744');
diff --git a/ai-kit-admin/dist/index.js b/ai-kit-admin/dist/index.js
diff --git a/ai-kit-admin/php/kb/admin.php b/ai-kit-admin/php/kb/admin.php
@@ -1138,10 +1138,14 @@ private function getKbPostTypeOptions(): array
     private function getEffectiveSectionMetadata(object $section, ?object $override): array
     {
         $metadata = [];
+        $extra_meta = $section->extra_meta_json ? json_decode($section->extra_meta_json, true) : null;
 
         if ($section->title) {
             $metadata['title'] = $section->title;
         }
+        if (is_array($extra_meta) && !empty($extra_meta['description']) && is_string($extra_meta['description'])) {
+            $metadata['description'] = $extra_meta['description'];
+        }
         if ($section->category) {
             $metadata['category'] = $section->category;
         }
@@ -1264,6 +1268,9 @@ public function restGetPostKbData(\WP_REST_Request $request): \WP_REST_Response
                 'md' => $section->md,
                 'origin_hash' => $section->origin_hash,
                 'generated_at' => $section->generated_at,
+                'extra_meta' => $section->extra_meta_json
+                    ? json_decode($section->extra_meta_json, true)
+                    : null,
                 'has_override' => (bool) $override,
                 'needs_review' => false
             ];
@@ -1304,6 +1311,9 @@ public function restGetPostKbData(\WP_REST_Request $request): \WP_REST_Response
         return new \WP_REST_Response([
             'post_id' => $post_id,
             'post_title' => $post->post_title,
+            'post_excerpt' => has_excerpt($post_id)
+                ? get_the_excerpt($post_id)
+                : wp_trim_words(wp_strip_all_tags($post->post_content), 30, '...'),
             'post_type' => $post->post_type,
             'post_url' => get_permalink($post_id),
             'source' => $source ? [
diff --git a/ai-kit-admin/php/kb/parser.php b/ai-kit-admin/php/kb/parser.php
@@ -342,6 +342,7 @@ private function parseKbSectionBlock(\WP_Post $post, array $block, int $sort_ord
         $section_key = $attrs['sectionKey'] ?? null;
         $doc_key = $attrs['docKey'] ?? null;
         $title = $attrs['title'] ?? null;
+        $description = $attrs['description'] ?? null;
         $tags = $attrs['tags'] ?? null;
         $category = $attrs['category'] ?? null;
         $subcategory = $attrs['subcategory'] ?? null;
@@ -379,6 +380,7 @@ private function parseKbSectionBlock(\WP_Post $post, array $block, int $sort_ord
             'source_updated_at' => $post->post_modified,
             'extra_meta' => [
                 'block_type' => 'gutenberg',
+                'description' => $description,
                 'priority' => $priority,
             ],
         ];
@@ -412,6 +414,9 @@ private function parseGutenbergSimple(\WP_Post $post, array $blocks): array
             'md' => $markdown,
             'generated_at' => current_time('mysql'),
             'source_updated_at' => $post->post_modified,
+            'extra_meta' => [
+                'description' => $this->getPostDescription($post),
+            ],
         ];
 
         $section['origin_hash'] = $this->calculateOriginHash($section);
@@ -582,6 +587,7 @@ private function parseElementorWithSections(\WP_Post $post, array $elements): ar
                 'generated_at' => current_time('mysql'),
                 'source_updated_at' => $post->post_modified,
                 'extra_meta' => [
+                    'description' => $this->getPostDescription($post),
                     'source_type' => 'elementor',
                 ],
             ];
@@ -672,6 +678,7 @@ private function parseElementorKbSection(\WP_Post $post, array $element, int $so
         $section_key = $settings['kb_section_key'] ?? null;
         $doc_key = $settings['kb_doc_key'] ?? null;
         $doc_title = $settings['kb_doc_title'] ?? null;
+        $doc_description = $settings['kb_doc_description'] ?? null;
         $title = $settings['kb_title'] ?? null;
         $category = $settings['kb_category'] ?? null;
         $subcategory = $settings['kb_subcategory'] ?? null;
@@ -725,6 +732,7 @@ private function parseElementorKbSection(\WP_Post $post, array $element, int $so
             'generated_at' => current_time('mysql'),
             'source_updated_at' => $post->post_modified,
             'extra_meta' => [
+                'description' => $doc_description,
                 'source_type' => 'elementor',
                 'priority' => $priority,
             ],
@@ -844,6 +852,7 @@ private function parseElementorSimple(\WP_Post $post, array $elements): array
             'generated_at' => current_time('mysql'),
             'source_updated_at' => $post->post_modified,
             'extra_meta' => [
+                'description' => $this->getPostDescription($post),
                 'source_type' => 'elementor',
             ],
         ];
@@ -889,6 +898,9 @@ private function parseClassicPost(\WP_Post $post): array
             'md' => $markdown,
             'generated_at' => current_time('mysql'),
             'source_updated_at' => $post->post_modified,
+            'extra_meta' => [
+                'description' => $this->getPostDescription($post),
+            ],
         ];
 
         $section['origin_hash'] = $this->calculateOriginHash($section);
@@ -942,6 +954,20 @@ private function getPostTags(\WP_Post $post): ?array
         return array_map(fn($tag) => $tag->name, $tags);
     }
 
+    /**
+     * Get the best available post description/excerpt for metadata.
+     */
+    private function getPostDescription(\WP_Post $post): ?string
+    {
+        $description = has_excerpt($post->ID)
+            ? get_the_excerpt($post->ID)
+            : wp_trim_words(wp_strip_all_tags($post->post_content), 30, '...');
+
+        $description = trim((string) $description);
+
+        return $description !== '' ? $description : null;
+    }
+
     /**
      * Generate a stable section ID from block data
      */
diff --git a/ai-kit-blocks/dist/editor.asset.php b/ai-kit-blocks/dist/editor.asset.php
@@ -1 +1 @@
-<?php return array('dependencies' => array('react', 'react-dom', 'react-jsx-runtime', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-data', 'wp-element', 'wp-i18n'), 'version' => '4626d5e6b69eba621932');
+<?php return array('dependencies' => array('react', 'react-dom', 'react-jsx-runtime', 'wp-block-editor', 'wp-blocks', 'wp-components', 'wp-data', 'wp-element', 'wp-i18n'), 'version' => 'ce7a317b779454e7ef4a');
diff --git a/ai-kit-blocks/dist/editor.js b/ai-kit-blocks/dist/editor.js
diff --git a/ai-kit-blocks/dist/kb-section/block.json b/ai-kit-blocks/dist/kb-section/block.json
@@ -24,6 +24,9 @@
     "title": {
       "type": "string"
     },
+    "description": {
+      "type": "string"
+    },
     "tags": {
       "type": "array",
       "default": [],
diff --git a/ai-kit-blocks/src/kb-section/block.json b/ai-kit-blocks/src/kb-section/block.json
@@ -24,6 +24,9 @@
     "title": {
       "type": "string"
     },
+    "description": {
+      "type": "string"
+    },
     "tags": {
       "type": "array",
       "default": [],
diff --git a/ai-kit-blocks/src/kb-section/edit.tsx b/ai-kit-blocks/src/kb-section/edit.tsx
@@ -19,6 +19,7 @@ interface EditProps {
     sectionKey?: string;
     docKey?: string;
     title?: string;
+    description?: string;
     tags?: string[];
     category?: string;
     subcategory?: string;
@@ -39,6 +40,7 @@ export default function Edit({
     sectionKey,
     docKey,
     title,
+    description,
     tags,
     category,
     subcategory,
@@ -136,6 +138,21 @@ export default function Edit({
                 placeholder="e.g., Pricing Information"
                 required
               />
+              <TextareaControl
+                label={__("Document Description", "smartcloud-ai-kit")}
+                value={description || ""}
+                onChange={(value: string) =>
+                  setAttributes({ description: value })
+                }
+                help={__(
+                  "Optional description stored in document metadata. Leave empty to fall back to the source post excerpt.",
+                  "smartcloud-ai-kit",
+                )}
+                placeholder={__(
+                  "Short summary shown in Doc Search results...",
+                  "smartcloud-ai-kit",
+                )}
+              />
             </>
           )}
 
diff --git a/elementor-kb-section-widget.php b/elementor-kb-section-widget.php
@@ -104,6 +104,20 @@ public static function add_kb_controls($element, $args): void
             ]
         );
 
+        $element->add_control(
+            'kb_doc_description',
+            [
+                'label' => __('Document Description', 'smartcloud-ai-kit'),
+                'type' => \Elementor\Controls_Manager::TEXTAREA,
+                'placeholder' => __('Short summary shown in Doc Search results', 'smartcloud-ai-kit'),
+                'description' => __('Optional description stored in document metadata. Leave empty to use the source post excerpt.', 'smartcloud-ai-kit'),
+                'condition' => [
+                    'kb_enabled' => 'yes',
+                    'kb_mode' => 'separate_doc',
+                ],
+            ]
+        );
+
         $element->add_control(
             'kb_section_key',
             [
diff --git a/readme.txt b/readme.txt
@@ -4,7 +4,7 @@ Tags: ai, chrome, seo, language, tools
 Requires at least: 6.2
 Tested up to: 6.9
 Requires PHP: 8.1
-Stable tag: 1.2.13
+Stable tag: 1.2.14
 License: MIT
 License URI: https://mit-license.org/
 Text Domain: smartcloud-ai-kit
@@ -199,6 +199,11 @@ AI-Kit Pro includes additional functionality (such as the AI-Kit Chatbot, backen
 
 == Changelog ==
 
+= 1.2.14 =
+* Feature: Added a document description override option in the KB admin/editor UI.
+* Feature: The overridden description is used as the excerpt shown below the title in DocSearch result lists.
+* UX: Gives editors more control over how Knowledge Base documents appear in search results.
+
 = 1.2.13 =
 * Feature: Extended the KB admin editing UI for generated documents and sections.
 * Feature: Base document metadata can now be overridden even for automatically enabled KB sources that do not have a dedicated KB Section override.
@@ -338,6 +343,9 @@ Fixed the pre-run language detection/translation flow for AiFeature blocks so it
 
 == Upgrade Notice ==
 
+= 1.2.14 =
+Adds a document description override option for Knowledge Base documents. The custom description is used as the excerpt shown under the title in DocSearch results.
+
 = 1.2.13 =
 Improves the KB admin editor for generated content. You can now override base document metadata and the Knowledge Base document title even for automatically enabled KB sources that do not have a dedicated KB Section override.
 
diff --git a/smartcloud-ai-kit.php b/smartcloud-ai-kit.php
@@ -6,7 +6,7 @@
  * Requires at least: 6.2
  * Tested up to:      6.9
  * Requires PHP:      8.1
- * Version:           1.2.13
+ * Version:           1.2.14
  * Author:            Smart Cloud Solutions Inc.
  * Author URI:        https://smart-cloud-solutions.com
  * License:           MIT
@@ -18,7 +18,7 @@
 
 namespace SmartCloud\WPSuite\AiKit;
 
-const VERSION = '1.2.13';
+const VERSION = '1.2.14';
 const DB_VERSION = '1.3.1';
 
 if (!defined('ABSPATH')) {

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-<?php return array('dependencies' => array('jquery', 'react', 'react-dom', 'react-jsx-runtime', 'wp-components', 'wp-data', 'wp-i18n'), 'version' => 'e972fb7777808103e323');`
	`1`	`+<?php return array('dependencies' => array('jquery', 'react', 'react-dom', 'react-jsx-runtime', 'wp-components', 'wp-data', 'wp-i18n'), 'version' => 'fb86e5d1fe3b40905744');`