feat: add llm_description prop

Author: araujogui

src/generators/llms-txt/utils/buildApiDocLink.mjs

@@ -1,6 +1,34 @@
 import { LATEST_DOC_API_BASE_URL } from '../../../constants.mjs';
 import { transformNodeToString } from '../../../utils/unist.mjs';
 
+/**
+ * Retrieves the description of a given API doc entry. It first checks whether
+ * the entry has a llm_description property. If not, it extracts the first
+ * paragraph from the entry's content.
+ *
+ * @param {ApiDocMetadataEntry} entry
+ * @returns {string}
+ */
+const getEntryDescription = entry => {
+  if (entry.llm_description) {
+    return entry.llm_description;
+  }
+
+  const descriptionNode = entry.content.children.find(
+    child => child.type === 'paragraph'
+  );
+
+  if (!descriptionNode) {
+    return '';
+  }
+
+  return (
+    transformNodeToString(descriptionNode)
+      // Remove newlines and extra spaces
+      .replace(/[\r\n]+/g, '')
+  );
+};
+
 /**
  * Builds a markdown link for an API doc entry
  *
@@ -16,18 +44,7 @@ export const buildApiDocLink = entry => {
 
   const link = `[${title}](${url})`;
 
-  // Find the first paragraph in the content
-  const descriptionNode = entry.content.children.find(
-    child => child.type === 'paragraph'
-  );
-
-  if (!descriptionNode) {
-    return link;
-  }
-
-  const description = transformNodeToString(descriptionNode)
-    // Remove newlines and extra spaces
-    .replace(/[\r\n]+/g, ' ');
+  const description = getEntryDescription(entry);
 
   return `${link}: ${description}`;
 };

src/metadata.mjs

@@ -131,6 +131,7 @@ const createMetadata = slugger => {
         updates = [],
         changes = [],
         tags = [],
+        llm_description,
       } = internalMetadata.properties;
 
       // Also add the slug to the heading data as it is used to build the heading
@@ -157,6 +158,7 @@ const createMetadata = slugger => {
         content: section,
         tags,
         introduced_in,
+        llm_description,
         yaml_position: internalMetadata.yaml_position,
       };
     },

src/types.d.ts

@@ -56,6 +56,7 @@ declare global {
     introduced_in?: string;
     napiVersion?: number;
     tags?: Array<string>;
+    llm_description?: string;
   }
 
   export interface ApiDocMetadataEntry {
@@ -90,6 +91,8 @@ declare global {
     // Extra YAML section entries that are stringd and serve
     // to provide additional metadata about the API doc entry
     tags: Array<string>;
+    // The llms.txt specific description
+    llm_description: string | undefined;
     // The postion of the YAML of the API doc entry
     yaml_position: Position;
   }

src/utils/parser/index.mjs

@@ -95,7 +95,8 @@ export const parseYAMLIntoMetadata = yamlString => {
     .replace('introduced_in=', 'introduced_in: ')
     .replace('source_link=', 'source_link: ')
     .replace('type=', 'type: ')
-    .replace('name=', 'name: ');
+    .replace('name=', 'name: ')
+    .replace('llm_description=', 'llm_description: ');
 
   // Ensures that the parsed YAML is an object, because even if it is not
   // i.e. a plain string or an array, it will simply not result into anything