@aigne/doc-smith 0.8.6 → 0.8.8

package/agents/{load-sources.mjs → utils/load-sources.mjs}

@@ -1,12 +1,12 @@
-import { access, readFile, stat } from "node:fs/promises";
+import { readFile, stat } from "node:fs/promises";
 import path from "node:path";
-import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../utils/constants.mjs";
-import { getFilesWithGlob, loadGitignore } from "../utils/file-utils.mjs";
+import { DEFAULT_EXCLUDE_PATTERNS, DEFAULT_INCLUDE_PATTERNS } from "../../utils/constants.mjs";
+import { getFilesWithGlob, loadGitignore } from "../../utils/file-utils.mjs";
 import {
   getCurrentGitHead,
   getModifiedFilesBetweenCommits,
   isGlobPattern,
-} from "../utils/utils.mjs";
+} from "../../utils/utils.mjs";
 
 export default async function loadSources({
   sources = [],
@@ -172,48 +172,61 @@ export default async function loadSources({
     }),
   );
 
-  // Get the last structure plan result
-  let originalStructurePlan;
-  const structurePlanPath = path.join(outputDir, "structure-plan.json");
-  try {
-    await access(structurePlanPath);
-    const structurePlanResult = await readFile(structurePlanPath, "utf8");
-    if (structurePlanResult) {
-      try {
-        originalStructurePlan = JSON.parse(structurePlanResult);
-      } catch (err) {
-        console.error(`Failed to parse structure-plan.json: ${err.message}`);
+  // Get the last document structure
+  let originalDocumentStructure;
+  if (outputDir) {
+    const documentStructurePath = path.join(outputDir, "structure-plan.json");
+    try {
+      const documentExecutionStructure = await readFile(documentStructurePath, "utf8");
+      if (documentExecutionStructure?.trim()) {
+        try {
+          // Validate that the content looks like JSON before parsing
+          const trimmedContent = documentExecutionStructure.trim();
+          if (trimmedContent.startsWith("{") || trimmedContent.startsWith("[")) {
+            originalDocumentStructure = JSON.parse(documentExecutionStructure);
+          } else {
+            console.warn(`structure-plan.json contains non-JSON content, skipping parse`);
+          }
+        } catch (err) {
+          console.error(`Failed to parse structure-plan.json: ${err.message}`);
+        }
+      }
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading structure-plan.json: ${err.message}`);
       }
+      // The file does not exist or is not readable, originalDocumentStructure remains undefined
     }
-  } catch {
-    // The file does not exist, originalStructurePlan remains undefined
   }
 
   // Get the last output result of the specified path
   let content;
-  if (docPath && !reset) {
-    let fileFullName;
-
+  if (docPath && !reset && docsDir) {
     // First try direct path matching (original format)
     const flatName = docPath.replace(/^\//, "").replace(/\//g, "-");
-    fileFullName = `${flatName}.md`;
+    const fileFullName = `${flatName}.md`;
     let filePath = path.join(docsDir, fileFullName);
 
     try {
-      await access(filePath);
       content = await readFile(filePath, "utf8");
-    } catch {
+    } catch (err) {
+      if (err.code !== "ENOENT") {
+        console.warn(`Error reading document file ${filePath}: ${err.message}`);
+      }
+
       // If not found and boardId is provided, try boardId-flattenedPath format
       if (boardId && docPath.startsWith(`${boardId}-`)) {
         // Extract the flattened path part after boardId-
         const flattenedPath = docPath.substring(boardId.length + 1);
-        fileFullName = `${flattenedPath}.md`;
-        filePath = path.join(docsDir, fileFullName);
+        const boardIdFileFullName = `${flattenedPath}.md`;
+        filePath = path.join(docsDir, boardIdFileFullName);
 
         try {
-          await access(filePath);
           content = await readFile(filePath, "utf8");
-        } catch {
+        } catch (boardIdErr) {
+          if (boardIdErr.code !== "ENOENT") {
+            console.warn(`Error reading document file ${filePath}: ${boardIdErr.message}`);
+          }
           // The file does not exist, content remains undefined
         }
       }
@@ -286,7 +299,7 @@ export default async function loadSources({
     datasourcesList: sourceFiles,
     datasources: allSources,
     content,
-    originalStructurePlan,
+    originalDocumentStructure,
     files,
     modifiedFiles,
     totalWords,

package/agents/{save-docs.mjs → utils/save-docs.mjs}

@@ -1,17 +1,17 @@
 import { readdir, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
-import { getCurrentGitHead, saveGitHeadToConfig } from "../utils/utils.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
+import { getCurrentGitHead, saveGitHeadToConfig } from "../../utils/utils.mjs";
 
 /**
  * @param {Object} params
- * @param {Array<{path: string, content: string, title: string}>} params.structurePlan
+ * @param {Array<{path: string, content: string, title: string}>} params.documentStructure
  * @param {string} params.docsDir
  * @param {Array<string>} [params.translateLanguages] - Translation languages
  * @returns {Promise<Array<{ path: string, success: boolean, error?: string }>>}
  */
 export default async function saveDocs({
-  structurePlanResult: structurePlan,
+  documentExecutionStructure: documentStructure,
   docsDir,
   translateLanguages = [],
   locale,
@@ -28,23 +28,23 @@ export default async function saveDocs({
 
   // Generate _sidebar.md
   try {
-    const sidebar = generateSidebar(structurePlan);
+    const sidebar = generateSidebar(documentStructure);
     const sidebarPath = join(docsDir, "_sidebar.md");
     await writeFile(sidebarPath, sidebar, "utf8");
   } catch (err) {
     console.error("Failed to save _sidebar.md:", err.message);
   }
 
-  // Clean up invalid .md files that are no longer in the structure plan
+  // Clean up invalid .md files that are no longer in the document structure
   try {
-    await cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, locale);
+    await cleanupInvalidFiles(documentStructure, docsDir, translateLanguages, locale);
   } catch (err) {
     console.error("Failed to cleanup invalid .md files:", err.message);
   }
 
   const message = `## ✅ Documentation Generated Successfully!
 
-  Successfully generated **${structurePlan.length}** documents and saved to:
+  Successfully generated **${documentStructure.length}** documents and saved to:
   \`${docsDir}\`
   ${projectInfoMessage || ""}
   ### 🚀 Next Steps
@@ -100,14 +100,14 @@ function generateFileName(flatName, language) {
 }
 
 /**
- * Clean up .md files that are no longer in the structure plan
- * @param {Array<{path: string, title: string}>} structurePlan
+ * Clean up .md files that are no longer in the document structure
+ * @param {Array<{path: string, title: string}>} documentStructure
  * @param {string} docsDir
  * @param {Array<string>} translateLanguages
  * @param {string} locale - Main language locale (e.g., 'en', 'zh', 'fr')
  * @returns {Promise<Array<{ path: string, success: boolean, error?: string }>>}
  */
-async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, locale) {
+async function cleanupInvalidFiles(documentStructure, docsDir, translateLanguages, locale) {
   const results = [];
 
   try {
@@ -115,11 +115,11 @@ async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, l
     const files = await readdir(docsDir);
     const mdFiles = files.filter((file) => file.endsWith(".md"));
 
-    // Generate expected file names from structure plan
+    // Generate expected file names from document structure
     const expectedFiles = new Set();
 
     // Add main document files
-    for (const { path } of structurePlan) {
+    for (const { path } of documentStructure) {
       const flatName = path.replace(/^\//, "").replace(/\//g, "-");
 
       // Main language file
@@ -166,11 +166,11 @@ async function cleanupInvalidFiles(structurePlan, docsDir, translateLanguages, l
   return results;
 }
 
-// Generate sidebar content, support nested structure, and the order is consistent with structurePlan
-function generateSidebar(structurePlan) {
+// Generate sidebar content, support nested structure, and the order is consistent with documentStructure
+function generateSidebar(documentStructure) {
   // Build tree structure
   const root = {};
-  for (const { path, title, parentId } of structurePlan) {
+  for (const { path, title, parentId } of documentStructure) {
     const relPath = path.replace(/^\//, "");
     const segments = relPath.split("/");
     let node = root;

package/agents/{save-single-doc.mjs → utils/save-single-doc.mjs}

@@ -1,5 +1,5 @@
-import { shutdownMermaidWorkerPool } from "../utils/mermaid-worker-pool.mjs";
-import { saveDocWithTranslations } from "../utils/utils.mjs";
+import { shutdownMermaidWorkerPool } from "../../utils/mermaid-worker-pool.mjs";
+import { saveDocWithTranslations } from "../../utils/utils.mjs";
 
 export default async function saveSingleDoc({
   path,

package/agents/{transform-detail-datasources.mjs → utils/transform-detail-datasources.mjs}

@@ -1,4 +1,4 @@
-import { normalizePath, toRelativePath } from "../utils/utils.mjs";
+import { normalizePath, toRelativePath } from "../../utils/utils.mjs";
 
 export default function transformDetailDatasources({ sourceIds, datasourcesList }) {
   // Build a map for fast lookup, with path normalization for compatibility

package/aigne.yaml

@@ -6,49 +6,49 @@ chat_model:
   # name: gemini-2.5-flash
   temperature: 0.8
 agents:
-  - ./agents/structure-planning.yaml
-  - ./agents/batch-docs-detail-generator.yaml
-  - ./agents/load-sources.mjs
-  - ./agents/save-docs.mjs
-  - ./agents/translate.yaml
-  - ./agents/detail-generator-and-translate.yaml
-  - ./agents/check-detail.mjs
-  - ./agents/transform-detail-datasources.mjs
-  - ./agents/batch-translate.yaml
-  - ./agents/save-single-doc.mjs
-  - ./agents/save-output.mjs
-  - ./agents/check-structure-plan.mjs
-  - ./agents/content-detail-generator.yaml
-  - ./agents/reflective-structure-planner.yaml
-  - ./agents/check-structure-planning-result.yaml
-  - ./agents/input-generator.mjs
-  - ./agents/docs-generator.yaml
-  - ./agents/detail-regenerator.yaml
-  - ./agents/publish-docs.mjs
-  - ./agents/format-structure-plan.mjs
-  - ./agents/load-config.mjs
-  - ./agents/team-publish-docs.yaml
-  - ./agents/find-item-by-path.mjs
-  - ./agents/retranslate.yaml
-  - ./agents/language-selector.mjs
+  - ./agents/generate/generate-structure.yaml
+  - ./agents/update/batch-generate-document.yaml
+  - ./agents/utils/load-sources.mjs
+  - ./agents/utils/save-docs.mjs
+  - ./agents/translate/translate-document.yaml
+  - ./agents/update/generate-and-translate-document.yaml
+  - ./agents/update/check-document.mjs
+  - ./agents/utils/transform-detail-datasources.mjs
+  - ./agents/translate/translate-multilingual.yaml
+  - ./agents/utils/save-single-doc.mjs
+  - ./agents/utils/save-output.mjs
+  - ./agents/generate/check-need-generate-structure.mjs
+  - ./agents/update/generate-document.yaml
+  - ./agents/generate/refine-document-structure.yaml
+  - ./agents/generate/check-document-structure.yaml
+  - ./agents/init/index.mjs
+  - ./agents/generate/index.yaml
+  - ./agents/update/index.yaml
+  - ./agents/publish/publish-docs.mjs
+  - ./agents/utils/format-document-structure.mjs
+  - ./agents/publish/index.yaml
+  - ./agents/utils/find-item-by-path.mjs
+  - ./agents/translate/index.yaml
+  - ./agents/translate/choose-language.mjs
   - ./docs-mcp/get-docs-structure.mjs
   - ./docs-mcp/get-docs-detail.mjs
   - ./docs-mcp/docs-search.yaml
   - ./docs-mcp/analyze-docs-relevance.yaml
   - ./docs-mcp/read-doc-content.mjs
   - ./docs-mcp/analyze-content-relevance.yaml
-  - ./agents/check-feedback-refiner.mjs
-  - ./agents/feedback-refiner.yaml
-  - ./agents/manage-prefs.mjs
+  - ./agents/utils/check-feedback-refiner.mjs
+  - ./agents/utils/feedback-refiner.yaml
+  - ./agents/prefs/index.mjs
+  - ./agents/chat/index.yaml
 cli:
-  chat: ./agents/chat.yaml
+  chat: ./agents/chat/index.yaml
   agents:
-    - ./agents/input-generator.mjs
-    - ./agents/docs-generator.yaml
-    - ./agents/detail-regenerator.yaml
-    - ./agents/team-publish-docs.yaml
-    - ./agents/retranslate.yaml
-    - ./agents/manage-prefs.mjs
+    - ./agents/init/index.mjs
+    - ./agents/generate/index.yaml
+    - ./agents/update/index.yaml
+    - ./agents/publish/index.yaml
+    - ./agents/translate/index.yaml
+    - ./agents/prefs/index.mjs
 mcp_server:
   agents:
     - ./docs-mcp/get-docs-structure.mjs

package/docs-mcp/analyze-docs-relevance.yaml

@@ -1,19 +1,19 @@
 name: analyze-docs-relevance
-description: Analyze which documents in the structure plan are relevant to the user query
+description: Analyze which documents in the document structure are relevant to the user query
 instructions: |
-  You are an AI assistant that analyzes the relevance between a user query and documents in a structure plan.
+  You are an AI assistant that analyzes the relevance between a user query and documents in a document structure.
 
-  <structure-plan>
-  {{ originalStructurePlan }}
-  </structure-plan>
+  <document_structure>
+  {{ originalDocumentStructure }}
+  </document_structure>
 
   <user-query>
   {{ query }}
   </user-query>
 
-  Given a user query and a structure plan containing multiple documents, your task is to:
+  Given a user query and a document structure containing multiple documents, your task is to:
   1. Understand the user's search intent from the query
-  2. Analyze each document in the structure plan to determine relevance
+  2. Analyze each document in the document structure to determine relevance
   3. Return a list of relevant documents with their paths, titles, and descriptions
 
   Consider the following factors for relevance:
@@ -33,7 +33,7 @@ input_schema:
     query:
       type: string
       description: User search query
-    originalStructurePlan:
+    originalDocumentStructure:
       type: array
       items:
         type: object
@@ -44,7 +44,7 @@ input_schema:
             type: string
           description:
             type: string
-      description: Structure plan containing all available documents
+      description: Document structure containing all available documents
 output_schema:
   type: object
   properties:
@@ -52,7 +52,7 @@ output_schema:
       type: array
       items:
         type: string
-        description: Must be selected from paths in the structure plan, cannot be other paths
+        description: Must be selected from paths in the document structure, cannot be other paths
       description: List of relevant documents
     reasoning:
       type: string

package/docs-mcp/docs-search.yaml

@@ -2,8 +2,10 @@ type: team
 name: docs-search
 description: Search relevant documents based on user query
 skills:
-  - ../agents/load-config.mjs
-  - ../agents/load-sources.mjs
+  - url: ../agents/init/index.mjs
+    default_input:
+      skipIfExists: true
+  - ../agents/utils/load-sources.mjs
   - analyze-docs-relevance.yaml
   - read-doc-content.mjs
   - analyze-content-relevance.yaml
@@ -36,5 +38,5 @@ output_schema:
             type: string
           description:
             type: string
-      description: List of relevant documents from structure plan
+      description: List of relevant documents from document structure
 mode: sequential

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/doc-smith",
-  "version": "0.8.6",
+  "version": "0.8.8",
   "description": "",
   "publishConfig": {
     "access": "public"
@@ -12,13 +12,14 @@
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "license": "MIT",
   "dependencies": {
-    "@aigne/aigne-hub": "^0.8.10",
-    "@aigne/anthropic": "^0.12.3",
-    "@aigne/cli": "^1.44.3",
-    "@aigne/core": "^1.58.3",
-    "@aigne/gemini": "^0.12.3",
-    "@aigne/openai": "^0.14.3",
-    "@aigne/publish-docs": "^0.9.6",
+    "@aigne/aigne-hub": "^0.9.3",
+    "@aigne/anthropic": "^0.13.3",
+    "@aigne/cli": "^1.46.2",
+    "@aigne/core": "^1.60.2",
+    "@aigne/gemini": "^0.13.3",
+    "@aigne/openai": "^0.15.3",
+    "@aigne/publish-docs": "^0.10.0",
+    "@terrastruct/d2": "^0.1.33",
     "chalk": "^5.5.0",
     "debug": "^4.4.1",
     "dompurify": "^3.2.6",
@@ -43,6 +44,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "test:coverage2": "bun test --coverage",
     "test:coverage": "bun test --coverage --coverage-reporter=lcov --coverage-reporter=text",
     "test:watch": "bun test --watch",
     "lint": "biome check",

package/prompts/{document → detail/custom}/custom-code-block.md

@@ -1,4 +1,4 @@
-<custom_code_block>
+<enhanced_code_block_rules>
 ## Enhanced Attributes for Markdown Code Blocks
 
 When generating Markdown, you can add enhanced attributes to code blocks to provide richer functionality and better display effects. These attributes allow you to specify **titles**, **icons**, and more for code blocks.
@@ -20,7 +20,7 @@ The following are the available enhanced attributes and their descriptions:
 
 ### Examples
 
-<good_example>
+<code_block_good_examples>
 The following are some examples of Markdown code blocks using enhanced attributes:
 
 **Example 1: Code block with title and icon**
@@ -70,9 +70,9 @@ class ShoppingCart {
   }
 }
 ```
-</good_example>
+</code_block_good_examples>
 
-<bad_example>
+<code_block_bad_examples>
 **Example 1**
 
 There are two errors in this example:
@@ -97,5 +97,5 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
-</bad_example>
-</custom_code_block>
+</code_block_bad_examples>
+</enhanced_code_block_rules>

package/prompts/detail/custom/custom-components.md

@@ -0,0 +1,172 @@
+<custom_components_usage>
+When generating document details, you can use the following custom components at appropriate locations based on their descriptions and functionality to enhance document presentation:
+- `<x-card>`
+- `<x-cards>`
+- `<x-field>`
+
+
+### 1. <x-card> Single Card Component
+Suitable for displaying individual links with a richer and more visually appealing presentation format.
+
+Example:
+
+```
+<x-card data-title="Required Title" data-image="Image URL" data-icon="Icon identifier (e.g., lucide:rocket or material-symbols:rocket-outline)" data-href="Navigation link URL" data-horizontal="true/false" data-cta="Button text" >
+  Card body content
+</x-card>
+```
+
+Attribute Rules:
+
+-	data-title (required): Card title.
+-	data-icon / data-image (choose one, at least one must be provided):
+    -	It's recommended to always provide data-icon.
+    -	Icons should prioritize Lucide (lucide:icon-name). If not available in Lucide, use Iconify (collection:icon-name, e.g., material-symbols:rocket-outline).
+-	data-image (optional): Image URL, can coexist with icon.
+-	data-href (optional): Navigation link for clicking the card or button.
+-	data-horizontal (optional): Whether to use horizontal layout.
+-	data-cta (optional): Button text (call to action).
+-	Body content: 
+  - Must be written within <x-card>...</x-card> children.
+  - **Markdown format rendering is not supported**
+  - **Code block rendering is not supported**
+  - Only supports plain text format without styling
+
+
+### 2. `<x-field>` Structured Field Component
+
+Suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types.
+
+Syntax:
+
+```
+<x-field data-name="field_name" data-type="string" data-default="default_value" data-required="true" data-deprecated="false" data-desc="Field description">
+  <!-- For complex types, children can only be other x-field elements -->
+  <x-field data-name="nested_field" data-type="string" data-desc="Nested field description"></x-field>
+</x-field>
+```
+
+Attribute Rules:
+
+- `data-name` (required): The name of the field/parameter
+- `data-type` (required): The data type of the field (e.g., "string", "number", "boolean", "object", "array")
+- `data-default` (optional): Default value for the field
+- `data-required` (optional): Whether the field is required ("true" or "false")
+- `data-deprecated` (optional): Whether the field is deprecated ("true" or "false")
+- `data-desc` (optional): Description of the field (replaces previous body content)
+- Children: For complex types (object, array), children can only be other `<x-field>` elements. For simple types, children can be empty.
+
+Nesting Rules:
+
+- Maximum nesting depth: 5 levels (to avoid overly complex structures)
+- Children elements must only be `<x-field>` components
+- Use `data-desc` attribute for field descriptions instead of body content
+- **Always use opening/closing tags format**: `<x-field ...></x-field>` for all types
+- For simple types (string, number, boolean), children can be empty: `<x-field ...></x-field>`
+- For complex types (object, array), children contain nested `<x-field>` elements
+
+**Usage Rules:**
+
+- **Context types must use `<x-field>` instead of tables** for consistent formatting
+
+Example:
+
+```
+<!-- Single field -->
+<x-field data-name="user_id" data-type="string" data-default="u0911" data-required="true" data-deprecated="true" data-desc="Unique identifier for the user. Must be a valid UUID v4 format."></x-field>
+
+<!-- Multiple related fields (Props, Parameters, Returns, Context) -->
+<x-field data-name="name" data-type="string" data-required="true" data-desc="The name of the product."></x-field>
+<x-field data-name="description" data-type="string" data-required="false" data-desc="An optional description for the product."></x-field>
+<x-field data-name="type" data-type="string" data-required="false" data-desc="The type of product (e.g., 'service', 'good')."></x-field>
+
+<!-- Complex nested object -->
+<x-field data-name="session" data-type="object" data-required="true" data-desc="User session information containing authentication and permission data">
+    <x-field data-name="auth" data-type="object" data-required="true" data-desc="User authentication information">
+        <x-field data-name="token" data-type="object" data-required="true" data-desc="Access token information">
+            <x-field data-name="access_token" data-type="string" data-required="true" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." data-desc="JWT access token for API authentication"></x-field>
+            <x-field data-name="refresh_token" data-type="string" data-required="false" data-default="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." data-desc="Refresh token for obtaining new access tokens"></x-field>
+            <x-field data-name="expires_at" data-type="number" data-required="true" data-default="1704067200" data-desc="Token expiration timestamp (Unix timestamp)"></x-field>
+        </x-field>
+        <x-field data-name="user" data-type="object" data-required="true" data-desc="User basic information">
+            <x-field data-name="profile" data-type="object" data-required="true" data-desc="User profile information">
+                <x-field data-name="name" data-type="string" data-required="true" data-default="John Doe" data-desc="User name"></x-field>
+                <x-field data-name="email" data-type="string" data-required="true" data-default="john.doe@example.com" data-desc="User email address"></x-field>
+                <x-field data-name="avatar" data-type="string" data-required="false" data-default="https://example.com/avatars/john-doe.jpg" data-desc="User avatar URL"></x-field>
+            </x-field>
+            <x-field data-name="permissions" data-type="array" data-required="true" data-default='["read", "write", "admin"]' data-desc="User permissions list"></x-field>
+        </x-field>
+    </x-field>
+</x-field>
+```
+
+### 3. `<x-cards>` Card List Component
+
+Suitable for displaying multiple links using a card list format, providing a richer and more visually appealing presentation.
+
+Syntax:
+
+```
+<x-cards data-columns="Number of columns">
+  <x-card data-title="Title 1" data-icon="lucide:rocket">Content 1</x-card>
+  <x-card data-title="Title 2" data-icon="lucide:bolt">Content 2</x-card>
+  <x-card data-title="Title 3" data-icon="material-symbols:rocket-outline">Content 3</x-card>
+</x-cards>
+```
+
+Attribute Rules:
+-	data-columns (optional): Number of columns, integer (e.g., 2, 3). Default is 2.
+-	Must contain multiple <x-card> elements internally.
+-	Consistency requirement: All <x-card> elements within the same <x-cards> must maintain visual consistency:
+    -	Recommended to always provide data-icon for each card.
+    -	Or all cards should have data-image.
+    -	Avoid mixing (some with icons, some with only images).
+
+<custom_components_good_example>
+Use plain text without any styling
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> SIGALRM: Sent when a real-time timer has expired.  </x-card>
+
+Single card:
+<x-card data-title="Horizontal card" data-icon="lucide:atom" data-horizontal="true">
+  This is an example of a horizontal card.
+</x-card>
+
+Card list (all using icons, recommended approach):
+<x-cards data-columns="3">
+  <x-card data-title="Feature 1" data-icon="lucide:rocket">Description of Feature 1.</x-card>
+  <x-card data-title="Feature 2" data-icon="lucide:bolt">Description of Feature 2.</x-card>
+  <x-card data-title="Feature 3" data-icon="material-symbols:rocket-outline">Description of Feature 3.</x-card>
+</x-cards>
+
+Card list (all using images):
+<x-cards data-columns="2">
+  <x-card data-title="Card A" data-image="https://picsum.photos/id/10/300/300">Content A</x-card>
+  <x-card data-title="Card B" data-image="https://picsum.photos/id/11/300/300">Content B</x-card>
+</x-cards>
+</custom_components_good_example>
+
+<custom_components_bad_example>
+
+`x-card` component body does not support markdown formatting inline code block
+<x-card data-title="alarm()" data-icon="lucide:alarm-clock"> `SIGALRM`: Sent when a real-time timer has expired.  </x-card>
+
+
+`x-card` component body does not support code blocks
+<x-card data-title="ctrl_break()" data-icon="lucide:keyboard">
+Creates a listener for "ctrl-break" events.
+```rust,no_run
+use tokio::signal::windows::ctrl_break;
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+let mut stream = ctrl_break()?;
+stream.recv().await;
+println!("got ctrl-break");
+Ok(())
+}
+```
+</x-card>
+
+</custom_components_bad_example>
+
+</custom_components_usage>