@qualcomm-ui/mdx-vite 2.7.0 → 2.9.0

package/dist/cli.js

@@ -3554,11 +3554,20 @@ var knowledgeExtraFileSchema = implement().with({
   id: z2.string(),
   title: z2.string()
 });
+var knowledgeExportsSchema = implement().with({
+  enabled: z2.boolean().optional(),
+  exclude: z2.array(z2.string()).optional(),
+  extraFiles: z2.array(knowledgeExtraFileSchema).optional(),
+  metadata: z2.record(z2.string(), z2.string()).optional(),
+  pageTitlePrefix: z2.string().optional(),
+  staticPath: z2.string().optional()
+});
 var knowledgeIntegrationSchema = implement().with(
   {
     baseUrl: z2.string().optional(),
     description: z2.string().optional(),
     exclude: z2.array(z2.string()).optional(),
+    exports: knowledgeExportsSchema.optional(),
     extraFiles: z2.array(knowledgeExtraFileSchema).optional(),
     metadata: z2.record(z2.string(), z2.string()).optional(),
     name: z2.string().optional(),
@@ -3604,6 +3613,7 @@ function defined(value) {
 }
 var frontmatterSchema = implement().with({
   categories: z3.string().array().optional(),
+  description: z3.string().optional(),
   group: z3.string().optional(),
   hidden: z3.boolean().optional(),
   hideBreadcrumbs: z3.boolean().optional(),
@@ -4353,6 +4363,36 @@ var alertToEmphasis = {
   warning: "warning"
 };
 
+// src/docs-plugin/remark/remark-frontmatter-interpolation.ts
+import { visit as visit4 } from "unist-util-visit";
+var FRONTMATTER_PATTERN = /^\s*frontmatter\.(\w+)\s*$/;
+function isMdxExpression(node) {
+  const n = node;
+  return (n.type === "mdxFlowExpression" || n.type === "mdxTextExpression") && typeof n.value === "string";
+}
+var remarkFrontmatterInterpolation = (frontmatter) => {
+  return (tree) => {
+    visit4(tree, (node, index, parent) => {
+      if (!isMdxExpression(node) || index === void 0 || !parent) {
+        return;
+      }
+      const match = node.value.match(FRONTMATTER_PATTERN);
+      if (!match) {
+        return;
+      }
+      const key = match[1];
+      const value = frontmatter[key];
+      if (typeof value === "string" || typeof value === "number") {
+        const textNode = {
+          type: "text",
+          value: String(value)
+        };
+        parent.children[index] = textNode;
+      }
+    });
+  };
+};
+
 // src/docs-plugin/internal/services/markdown/remark-remove-code-blocks.ts
 import { remove } from "unist-util-remove";
 var remarkRemoveMermaidCodeBlocks = () => {
@@ -4450,14 +4490,9 @@ var MarkdownIndexer = class {
     }
   }
   parseMarkdown(fileContents, frontmatter) {
-    const file = unified3().use(remarkMdx2).use(remarkRemoveJsx).use(remarkRemoveMermaidCodeBlocks).use(remarkParse3).use(remarkGfm).use(remarkAlerts).use(remarkRehype).use(rehypeStringify).processSync(fileContents);
+    const file = unified3().use(remarkMdx2).use(remarkRemoveJsx).use(remarkRemoveMermaidCodeBlocks).use(remarkParse3).use(remarkGfm).use(remarkAlerts).use(remarkFrontmatterInterpolation, frontmatter).use(remarkRehype).use(rehypeStringify).processSync(fileContents);
     let contents = file.toString();
     contents = contents.substring(contents.indexOf("<h1>"));
-    for (const [key, value] of Object.entries(frontmatter)) {
-      if (typeof value === "string" || typeof value === "number") {
-        contents = contents.replaceAll(`frontmatter.${key}`, `${value}`);
-      }
-    }
     const htmlAst = unified3().data("settings", { fragment: true }).use(rehypeParse).use(rehypeStringify).use(rehypeSlug).processSync(contents);
     contents = htmlAst.toString();
     return this.build(contents);
@@ -5036,6 +5071,7 @@ var SearchIndexer = class {
         this.metaJson,
         routeMeta?.title || frontmatter.title || ""
       ),
+      description: frontmatter.description,
       hidden: defined(routeMeta.hidden) ? routeMeta.hidden : frontmatter.hidden,
       hideBreadcrumbs: defined(routeMeta.hideBreadcrumbs) ? routeMeta.hideBreadcrumbs : frontmatter.hideBreadcrumbs,
       hideFromSearch: defined(routeMeta.hideFromSearch) ? routeMeta.hideFromSearch : frontmatter.hideFromSearch,
@@ -5621,14 +5657,14 @@ import {
   stat,
   writeFile as writeFile3
 } from "node:fs/promises";
-import { basename, dirname, extname, join as join3, relative as relative2, resolve as resolve5 } from "node:path";
+import { basename, dirname, extname, join as join4, relative as relative2, resolve as resolve5 } from "node:path";
 import remarkFrontmatter3 from "remark-frontmatter";
 import remarkMdx3 from "remark-mdx";
 import remarkParse4 from "remark-parse";
 import remarkParseFrontmatter2 from "remark-parse-frontmatter";
 import remarkStringify3 from "remark-stringify";
 import { unified as unified4 } from "unified";
-import { visit as visit7 } from "unist-util-visit";
+import { visit as visit10 } from "unist-util-visit";
 import { kebabCase } from "@qualcomm-ui/utils/change-case";
 
 // src/docs-plugin/docs-plugin.ts
@@ -5636,24 +5672,31 @@ import chalk3 from "chalk";
 import chokidar from "chokidar";
 import { glob as glob2 } from "glob";
 import { readFileSync as readFileSync2 } from "node:fs";
-import { resolve as resolve3 } from "node:path";
+import { join as join2, resolve as resolve3 } from "node:path";
 import prettyMilliseconds from "pretty-ms";
 var isDev = process.env.NODE_ENV === "development";
 var VIRTUAL_MODULE_ID = "\0@qualcomm-ui/mdx-vite-plugin";
 var PluginState = class {
   buildCount = 0;
+  config = null;
   configFilePath = "";
   docPropsFilePath = "";
+  exports = { basePath: "", enabled: false, pages: [] };
   indexer;
   configLoader = null;
+  knowledgeConfig = void 0;
   routesDir;
   servers = [];
   timeout = void 0;
+  exportsTimeout = void 0;
   watching = false;
   cwd;
   init(cwd2) {
     this.cwd = cwd2;
   }
+  getCwd() {
+    return this.cwd;
+  }
   get docPropsDirectory() {
     if (!this.docPropsFilePath) {
       return "";
@@ -5664,7 +5707,10 @@ var PluginState = class {
     );
   }
   get siteData() {
+    const { filePath: _filePath, ...config2 } = this.config ?? {};
     return {
+      config: config2,
+      exports: this.exports,
       navItems: state.indexer.navItems,
       pageDocProps: state.indexer.pageDocProps,
       pageMap: state.indexer.pageMap,
@@ -5685,14 +5731,24 @@ var PluginState = class {
     }
   }
   createIndexer(config2) {
+    this.config = config2;
     this.configFilePath = config2.filePath;
     this.docPropsFilePath = config2.typeDocProps ? fixPath(resolve3(this.cwd, config2.typeDocProps)) : "";
     this.routesDir = fixPath(resolve3(config2.appDirectory, config2.pageDirectory));
+    this.knowledgeConfig = config2.knowledge;
     this.indexer = new SearchIndexer({
       ...config2,
       srcDir: fixPath(resolve3(this.cwd, config2.appDirectory)),
       typeDocProps: this.resolveDocProps()
     });
+    const exportsConfig = config2.knowledge?.global?.exports;
+    const exportsEnabled = exportsConfig?.enabled ?? false;
+    const exportsPath = exportsConfig?.staticPath ?? "exports/md";
+    this.exports = {
+      basePath: exportsEnabled ? `/${exportsPath}` : "",
+      enabled: exportsEnabled,
+      pages: []
+    };
   }
   buildIndex(shouldLog) {
     const files = glob2.sync(
@@ -5765,6 +5821,41 @@ var PluginState = class {
       });
     });
   }
+  async generateExports(publicDir) {
+    if (!this.exports.enabled || !this.knowledgeConfig?.global) {
+      return;
+    }
+    const globalConfig = this.knowledgeConfig.global;
+    const exportsConfig = globalConfig.exports ?? {};
+    const exportsPath = exportsConfig.staticPath ?? "exports/md";
+    const outputPath = join2(publicDir, exportsPath);
+    const startTime = Date.now();
+    const pageIds = await generate({
+      baseUrl: globalConfig.baseUrl,
+      clean: true,
+      docPropsPath: this.docPropsFilePath || void 0,
+      exclude: exportsConfig.exclude ?? globalConfig.exclude,
+      extraFiles: exportsConfig.extraFiles ?? globalConfig.extraFiles,
+      metadata: exportsConfig.metadata ?? globalConfig.metadata,
+      outputMode: "per-page",
+      outputPath,
+      pageTitlePrefix: exportsConfig.pageTitlePrefix ?? globalConfig.pageTitlePrefix,
+      routeDir: this.routesDir
+    });
+    this.exports.pages = pageIds;
+    console.debug(
+      `${chalk3.magenta.bold(`@qualcomm-ui/mdx-vite/docs-plugin:`)} Generated Markdown exports in: ${chalk3.blueBright.bold(prettyMilliseconds(Date.now() - startTime))}`
+    );
+  }
+  debouncedGenerateExports(publicDir) {
+    if (!this.exports.enabled) {
+      return;
+    }
+    clearTimeout(this.exportsTimeout);
+    this.exportsTimeout = setTimeout(() => {
+      void this.generateExports(publicDir);
+    }, 500);
+  }
 };
 var state = new PluginState();
 
@@ -5793,11 +5884,17 @@ import { heading } from "hast-util-heading";
 import { headingRank as headingRank2 } from "hast-util-heading-rank";
 
 // src/docs-plugin/remark/remark-code-tabs.ts
-import { visit as visit4 } from "unist-util-visit";
+import { visit as visit5 } from "unist-util-visit";
+
+// src/docs-plugin/remark/remark-frontmatter-description.ts
+import { visit as visit6 } from "unist-util-visit";
+
+// src/docs-plugin/remark/remark-frontmatter-title.ts
+import { visit as visit7 } from "unist-util-visit";
 
 // src/docs-plugin/remark/remark-self-link-headings.ts
 import { toString as toString2 } from "mdast-util-to-string";
-import { visit as visit5 } from "unist-util-visit";
+import { visit as visit8 } from "unist-util-visit";
 var emptyOptions2 = {};
 function remarkSelfLinkHeadings(baseUrl = "", options) {
   if (!baseUrl) {
@@ -5825,7 +5922,7 @@ function remarkSelfLinkHeadings(baseUrl = "", options) {
     }
     return (tree) => {
       seenIds.clear();
-      visit5(tree, "heading", (node) => {
+      visit8(tree, "heading", (node) => {
         if (allowedLevels.has(node.depth)) {
           const text = toString2(node);
           const slug = prefix + createSlug(text);
@@ -5842,14 +5939,14 @@ function remarkSelfLinkHeadings(baseUrl = "", options) {
 }
 
 // src/docs-plugin/remark/remark-spoilers.ts
-import { visit as visit6 } from "unist-util-visit";
+import { visit as visit9 } from "unist-util-visit";
 
 // src/docs-plugin/shiki/shiki-transformer-preview-block.ts
 import { dedent } from "@qualcomm-ui/utils/dedent";
 
 // src/open-web-ui-knowledge/load-config-from-env.ts
 import { existsSync } from "node:fs";
-import { join as join2, resolve as resolve4 } from "node:path";
+import { join as join3, resolve as resolve4 } from "node:path";
 function parseCliMetadata(cliMetadata) {
   if (!cliMetadata?.length) {
     return void 0;
@@ -5865,7 +5962,7 @@ function loadKnowledgeConfigFromEnv(options) {
   if (!outputPath) {
     throw new Error("Missing required outputPath");
   }
-  const routeDir = join2(
+  const routeDir = join3(
     resolvedConfig.appDirectory,
     resolvedConfig.pageDirectory
   );
@@ -5942,7 +6039,7 @@ async function resolveModulePath(importPath, fromFile) {
     }
   }
   if (await exists(baseResolved)) {
-    const indexPath = join3(baseResolved, "index.ts");
+    const indexPath = join4(baseResolved, "index.ts");
     if (await exists(indexPath)) {
       return indexPath;
     }
@@ -5954,7 +6051,7 @@ function extractMetadata(metadata) {
 }
 var replaceNpmInstallTabs = () => {
   return (tree, _file, done) => {
-    visit7(tree, "mdxJsxFlowElement", (node) => {
+    visit10(tree, "mdxJsxFlowElement", (node) => {
       if (node?.name === "NpmInstallTabs") {
         const packages = node.attributes?.find(
           (attr) => attr.type === "mdxJsxAttribute" && attr.name === "packages"
@@ -5998,7 +6095,7 @@ var KnowledgeGenerator = class {
     this.docProps = docProps;
     if (pages.length === 0) {
       console.log("No pages found.");
-      return;
+      return [];
     }
     if (this.config.verbose) {
       console.log(`Found ${pages.length} page(s)`);
@@ -6031,9 +6128,10 @@ var KnowledgeGenerator = class {
       );
       await this.generateExtraFiles(extractedMetadata);
     }
+    return pages.map((page) => page.id);
   }
   async loadDocProps() {
-    const resolvedDocPropsPath = this.config.docPropsPath ? await exists(this.config.docPropsPath) ? this.config.docPropsPath : resolve5(process.cwd(), this.config.docPropsPath) : join3(dirname(this.config.routeDir), "doc-props.json");
+    const resolvedDocPropsPath = this.config.docPropsPath ? await exists(this.config.docPropsPath) ? this.config.docPropsPath : resolve5(process.cwd(), this.config.docPropsPath) : join4(dirname(this.config.routeDir), "doc-props.json");
     if (!await exists(resolvedDocPropsPath)) {
       if (this.config.verbose) {
         console.log(`Doc props file not found at: ${resolvedDocPropsPath}`);
@@ -6080,20 +6178,20 @@ var KnowledgeGenerator = class {
       }
       const entries = await readdir(dirPath, { withFileTypes: true });
       const mdxFiles = entries.filter(
-        (f) => f.name.endsWith(".mdx") && !shouldExclude(join3(dirPath, f.name))
+        (f) => f.name.endsWith(".mdx") && !shouldExclude(join4(dirPath, f.name))
       ) ?? [];
       for (const mdxFile of mdxFiles) {
         const demosFolder = entries.find((f) => f.name === "demos");
-        const demosFolderPath = demosFolder ? join3(dirPath, demosFolder.name) : void 0;
+        const demosFolderPath = demosFolder ? join4(dirPath, demosFolder.name) : void 0;
         const segments = getPathSegmentsFromFileName(
-          join3(dirPath, mdxFile.name),
+          join4(dirPath, mdxFile.name),
           this.config.routeDir
         );
         const url = getPathnameFromPathSegments(segments);
         components.push({
           demosFolder: demosFolderPath,
           id: segments.join("-").trim(),
-          mdxFile: join3(dirPath, mdxFile.name),
+          mdxFile: join4(dirPath, mdxFile.name),
           name: segments.at(-1),
           path: dirPath,
           url: this.config.baseUrl ? new URL(url, this.config.baseUrl).toString() : void 0
@@ -6104,7 +6202,7 @@ var KnowledgeGenerator = class {
         }
       }
       for (const entry of entries) {
-        const fullPath = join3(dirPath, entry.name);
+        const fullPath = join4(dirPath, entry.name);
         const stats = await stat(fullPath);
         if (stats.isDirectory()) {
           await scanDirectory(fullPath);
@@ -6270,7 +6368,7 @@ ${codeText}
       }
     };
     return () => (tree, _file, done) => {
-      visit7(tree, "mdxJsxFlowElement", (node) => {
+      visit10(tree, "mdxJsxFlowElement", (node) => {
         const handler = node.name && handlers[node.name];
         if (!handler) {
           return;
@@ -6310,7 +6408,7 @@ ${codeText}
    */
   replaceTypeDocProps() {
     return () => (tree, _file, done) => {
-      visit7(
+      visit10(
         tree,
         "mdxJsxFlowElement",
         (node, index, parent) => {
@@ -6371,7 +6469,7 @@ ${codeText}
   replaceDemos(demosFolder, demoFiles) {
     return () => async (tree) => {
       const promises = [];
-      visit7(
+      visit10(
         tree,
         "mdxJsxFlowElement",
         (node, index, parent) => {
@@ -6415,14 +6513,14 @@ ${codeText}
                 }
                 return;
               }
-              let demoFilePath = join3(demosFolder, filePath);
+              let demoFilePath = join4(demosFolder, filePath);
               let isAngularDemo = false;
               if (!await exists(demoFilePath)) {
-                demoFilePath = join3(demosFolder, `${kebabName}.ts`);
+                demoFilePath = join4(demosFolder, `${kebabName}.ts`);
                 if (await exists(demoFilePath)) {
                   isAngularDemo = true;
                   filePath = `${kebabCase(demoName).replace("-component", ".component")}.ts`;
-                  demoFilePath = join3(demosFolder, filePath);
+                  demoFilePath = join4(demosFolder, filePath);
                 } else {
                   console.log(`  Demo not found ${demoName}`);
                   if (parent && index !== void 0) {
@@ -6459,21 +6557,51 @@ ${codeText}
       await Promise.all(promises);
     };
   }
+  replaceFrontmatterExpressions(frontmatter) {
+    return () => (tree) => {
+      visit10(
+        tree,
+        "mdxFlowExpression",
+        (node, index, parent) => {
+          if (node.value.trim() !== "frontmatter.description" || index === void 0 || !parent) {
+            return;
+          }
+          if (frontmatter.description) {
+            parent.children.splice(index, 1, {
+              children: [{ type: "text", value: frontmatter.description }],
+              type: "paragraph"
+            });
+          } else {
+            parent.children.splice(index, 1);
+          }
+        }
+      );
+      const root = tree;
+      const h1Index = root.children.findIndex((node) => {
+        if (node.type !== "heading" || node.depth !== 1) {
+          return false;
+        }
+        return node.children?.some(
+          (child) => child.type === "mdxTextExpression" && child.value?.includes("frontmatter")
+        );
+      });
+      if (h1Index >= 0) {
+        root.children.splice(h1Index, 1);
+      }
+    };
+  }
   /**
    * Processes MDX content by transforming JSX elements (TypeDocProps, demos)
    * into markdown, resolving relative links, and cleaning up formatting.
    */
-  async processMdxContent(mdxContent, pageUrl, demosFolder) {
+  async processMdxContent(mdxContent, pageUrl, demosFolder, frontmatter) {
     const demoFiles = [];
     let processedContent = mdxContent;
-    const lines = processedContent.split("\n");
-    const titleLine = lines.findIndex((line) => line.startsWith("# "));
-    processedContent = titleLine >= 0 ? lines.slice(titleLine + 1).join("\n") : processedContent;
     processedContent = processedContent.replace(
       /\[([^\]]+)\]\(\.\/#([^)]+)\)/g,
       (_, text, anchor) => pageUrl && this.config.outputMode === "per-page" ? `[${text}](${pageUrl}#${anchor})` : text
     );
-    const processor = unified4().use(remarkParse4).use(remarkMdx3).use(this.replaceTypeDocProps()).use(await this.replaceThemeNodes()).use(this.replaceDemos(demosFolder, demoFiles)).use(remarkStringify3);
+    const processor = unified4().use(remarkParse4).use(remarkMdx3).use(remarkFrontmatter3, ["yaml"]).use(this.replaceTypeDocProps()).use(this.replaceFrontmatterExpressions(frontmatter)).use(await this.replaceThemeNodes()).use(this.replaceDemos(demosFolder, demoFiles)).use(remarkStringify3);
     const processed = await processor.process(processedContent);
     processedContent = String(processed);
     processedContent = processedContent.replace(/\n\s*\n\s*\n/g, "\n\n");
@@ -6495,9 +6623,10 @@ ${codeText}
       const { content: processedContent, demoFiles } = await this.processMdxContent(
         String(parsed),
         component.url,
-        component.demosFolder
+        component.demosFolder,
+        frontmatter
       );
-      const removeJsxProcessor = unified4().use(remarkParse4).use(remarkMdx3).use(remarkRemoveJsx).use(remarkStringify3);
+      const removeJsxProcessor = unified4().use(remarkParse4).use(remarkMdx3).use(remarkFrontmatter3, ["yaml"]).use(remarkRemoveJsx).use(remarkStringify3);
       const removedJsx = String(
         await removeJsxProcessor.process(processedContent)
       );
@@ -6672,7 +6801,7 @@ ${codeText}
 };
 async function generate(config2) {
   const generator = new KnowledgeGenerator(config2);
-  await generator.run();
+  return generator.run();
 }
 function addGenerateKnowledgeCommand() {
   program.description("Generate llms.txt from QUI Docs documentation").command("generate-llms-txt").option("-n, --name <name>", "Project name for llms.txt header").requiredOption("-m, --output-mode <outputMode>").option("-o, --outputPath <outputPath>", "Output file or directory.").option(
@@ -7020,7 +7149,7 @@ import { dedent as dedent2 } from "@qualcomm-ui/utils/dedent";
 // src/react-demo-plugin/demo-plugin-utils.ts
 import chalk4 from "chalk";
 import { existsSync as existsSync2, readFileSync as readFileSync3 } from "node:fs";
-import { dirname as dirname2, join as join4, relative as relative3, resolve as resolve7, sep } from "node:path";
+import { dirname as dirname2, join as join5, relative as relative3, resolve as resolve7, sep } from "node:path";
 import * as ts from "typescript";
 import { pascalCase } from "@qualcomm-ui/utils/change-case";
 function extractPageId(filePath, routesDir) {