F/mint text url preprocessing

.changeset/tasty-rockets-rule.md

@@ -0,0 +1,5 @@
+---
+'gtx-cli': patch
+---
+
+Wrapping text node URLs for Mintlify MDX to align with their parser

packages/cli/src/formats/files/__tests__/aggregateFiles.test.ts

@@ -286,6 +286,7 @@ describe('aggregateFiles - Empty File Handling', () => {
           placeholderPaths: {},
         },
         defaultLocale: 'en',
+        framework: 'mintlify',
         options: {
           mintlify: {
             inferTitleFromFilename: true,
@@ -312,6 +313,7 @@ describe('aggregateFiles - Empty File Handling', () => {
           placeholderPaths: {},
         },
         defaultLocale: 'en',
+        framework: 'mintlify',
         options: {
           mintlify: {
             inferTitleFromFilename: true,
@@ -343,6 +345,7 @@ describe('aggregateFiles - Empty File Handling', () => {
           placeholderPaths: {},
         },
         defaultLocale: 'en',
+        framework: 'mintlify',
         options: {
           mintlify: {
             inferTitleFromFilename: true,
@@ -369,6 +372,7 @@ describe('aggregateFiles - Empty File Handling', () => {
           placeholderPaths: {},
         },
         defaultLocale: 'es',
+        framework: 'mintlify',
         options: {
           mintlify: {
             inferTitleFromFilename: true,

packages/cli/src/formats/files/aggregateFiles.ts

@@ -4,14 +4,12 @@ import { getRelative, readFile } from '../../fs/findFilepath.js';
 import { Settings } from '../../types/index.js';
 import type { FileFormat, DataFormat, FileToUpload } from '../../types/data.js';
 import { SUPPORTED_FILE_EXTENSIONS } from './supportedFiles.js';
-import sanitizeFileContent from '../../utils/sanitizeFileContent.js';
 import { parseJson } from '../json/parseJson.js';
 import parseYaml from '../yaml/parseYaml.js';
 import YAML from 'yaml';
 import { determineLibrary } from '../../fs/determineFramework.js';
-import { isValidMdx } from '../../utils/validateMdx.js';
 import { hashStringSync } from '../../utils/hash.js';
-import { applyMintlifyTitleFallback } from '../../utils/mintlifyTitleFallback.js';
+import { preprocessContent } from './preprocessContent.js';
 export const SUPPORTED_DATA_FORMATS = ['JSX', 'ICU', 'I18NEXT'];
 
 export async function aggregateFiles(
@@ -159,48 +157,25 @@ export async function aggregateFiles(
           const content = readFile(filePath);
           const relativePath = getRelative(filePath);
 
-          if (fileType === 'mdx') {
-            if (!skipValidation?.mdx) {
-              const validation = isValidMdx(content, filePath);
-              if (!validation.isValid) {
-                logger.warn(
-                  `Skipping ${relativePath}: MDX file is not AST parsable${validation.error ? `: ${validation.error}` : ''}`
-                );
-                recordWarning(
-                  'skipped_file',
-                  relativePath,
-                  `MDX file is not AST parsable${validation.error ? `: ${validation.error}` : ''}`
-                );
-                return null;
-              }
-            }
-          }
+          const processed = preprocessContent(
+            content,
+            relativePath,
+            fileType,
+            settings
+          );
 
-          let processedContent = content;
-          let addedMintlifyTitle = false;
-          if (
-            fileType === 'mdx' &&
-            settings.options?.mintlify?.inferTitleFromFilename
-          ) {
-            const result = applyMintlifyTitleFallback(
-              processedContent,
-              relativePath,
-              settings.defaultLocale
-            );
-            processedContent = result.content;
-            addedMintlifyTitle = result.addedTitle;
+          if (typeof processed !== 'string') {
+            logger.warn(`Skipping ${relativePath}: ${processed.skip}`);
+            recordWarning('skipped_file', relativePath, processed.skip);
+            return null;
           }
 
-          const sanitizedContent = sanitizeFileContent(processedContent);
-          // Always hash original content for versionId
-          const computedVersionId = hashStringSync(content);
-
           return {
-            content: sanitizedContent,
+            content: processed,
             fileName: relativePath,
             fileFormat: fileType.toUpperCase() as FileFormat,
             fileId: hashStringSync(relativePath),
-            versionId: computedVersionId,
+            versionId: hashStringSync(content),
             locale: settings.defaultLocale,
           } satisfies FileToUpload;
         })

packages/cli/src/formats/files/preprocess/mdx.ts

@@ -0,0 +1,20 @@
+import { Settings } from '../../../types/index.js';
+import { isValidMdx } from '../../../utils/validateMdx.js';
+
+/**
+ * Runs MDX-specific preprocessing. Returns a skip reason if the file
+ * should be skipped, or null if validation passed.
+ */
+export function preprocessMdx(
+  content: string,
+  filePath: string,
+  settings: Settings
+): string | null {
+  if (!settings.options?.skipFileValidation?.mdx) {
+    const validation = isValidMdx(content, filePath);
+    if (!validation.isValid) {
+      return `MDX file is not AST parsable${validation.error ? `: ${validation.error}` : ''}`;
+    }
+  }
+  return null;
+}

packages/cli/src/formats/files/preprocess/mintlify.ts

@@ -0,0 +1,32 @@
+import { Settings } from '../../../types/index.js';
+import { applyMintlifyTitleFallback } from '../../../utils/mintlifyTitleFallback.js';
+import wrapPlainUrls from '../../../utils/wrapPlainUrls.js';
+
+/**
+ * Runs all Mintlify-specific preprocessing on file content.
+ */
+export function preprocessMintlify(
+  content: string,
+  filePath: string,
+  fileType: string,
+  settings: Settings
+): string {
+  let result = content;
+
+  if (
+    fileType === 'mdx' &&
+    settings.options?.mintlify?.inferTitleFromFilename
+  ) {
+    result = applyMintlifyTitleFallback(
+      result,
+      filePath,
+      settings.defaultLocale
+    ).content;
+  }
+
+  if (fileType === 'mdx') {
+    result = wrapPlainUrls(result);
+  }
+
+  return result;
+}

packages/cli/src/formats/files/preprocessContent.ts

@@ -0,0 +1,33 @@
+import { Settings } from '../../types/index.js';
+import { preprocessMdx } from './preprocess/mdx.js';
+import { preprocessMintlify } from './preprocess/mintlify.js';
+import sanitizeFileContent from '../../utils/sanitizeFileContent.js';
+
+/**
+ * Preprocesses file content before upload. Returns the processed content,
+ * or { skip: reason } if the file should be skipped.
+ */
+export function preprocessContent(
+  content: string,
+  filePath: string,
+  fileType: string,
+  settings: Settings
+): string | { skip: string } {
+  let result = content;
+
+  // File-type-specific
+  if (fileType === 'mdx') {
+    const skipReason = preprocessMdx(result, filePath, settings);
+    if (skipReason) return { skip: skipReason };
+  }
+
+  // Framework-specific
+  if (settings.framework === 'mintlify') {
+    result = preprocessMintlify(result, filePath, fileType, settings);
+  }
+
+  // Universal
+  result = sanitizeFileContent(result);
+
+  return result;
+}

packages/cli/src/generated/version.ts

@@ -1,2 +1,2 @@
 // This file is auto-generated. Do not edit manually.
-export const PACKAGE_VERSION = '2.6.27';
+export const PACKAGE_VERSION = '2.6.29';