gtx-cli 2.1.9 → 2.1.10

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # gtx-cli
 
+## 2.1.10
+
+### Patch Changes
+
+- [#600](https://github.com/generaltranslation/gt/pull/600) [`e94aac2`](https://github.com/generaltranslation/gt/commit/e94aac2b2554a279245d090b0872f6f64eb71c62) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Added handling of fragment URLs (i.e. href="#my-mdx-id") for correct routing across locales.
+
 ## 2.1.9
 
 ### Patch Changes

package/dist/cli/commands/translate.js

@@ -5,6 +5,7 @@ import { getStagedVersions } from '../../fs/config/updateVersions.js';
 import copyFile from '../../fs/copyFile.js';
 import flattenJsonFiles from '../../utils/flattenJsonFiles.js';
 import localizeStaticUrls from '../../utils/localizeStaticUrls.js';
+import processAnchorIds from '../../utils/processAnchorIds.js';
 import { noFilesError, noVersionIdError } from '../../console/index.js';
 // Downloads translations that were completed
 export async function handleTranslate(options, settings, filesTranslationResponse) {
@@ -34,13 +35,16 @@ export async function handleDownload(options, settings) {
     await checkFileTranslations(stagedVersionData, settings.locales, options.timeout, (sourcePath, locale) => fileMapping[locale][sourcePath] ?? null, settings);
 }
 export async function postProcessTranslations(settings) {
-    // Localize static urls (/docs -> /[locale]/docs) for non-default locales only
+    // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales
     // Default locale is processed earlier in the flow in base.ts
     if (settings.options?.experimentalLocalizeStaticUrls) {
         const nonDefaultLocales = settings.locales.filter((locale) => locale !== settings.defaultLocale);
         if (nonDefaultLocales.length > 0) {
             await localizeStaticUrls(settings, nonDefaultLocales);
         }
+        // Add explicit anchor IDs to translated MDX/MD files to preserve navigation
+        // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'
+        await processAnchorIds(settings);
     }
     // Flatten json files into a single file
     if (settings.options?.experimentalFlattenJsonFiles) {

package/dist/types/index.d.ts

@@ -21,6 +21,7 @@ export type Options = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
 };
 export type TranslateFlags = {
     config?: string;
@@ -41,6 +42,7 @@ export type TranslateFlags = {
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     experimentalLocalizeStaticImports?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
     excludeStaticUrls?: string[];
     excludeStaticImports?: string[];
 };
@@ -139,6 +141,7 @@ export type AdditionalOptions = {
     copyFiles?: string[];
     experimentalLocalizeStaticImports?: boolean;
     experimentalLocalizeStaticUrls?: boolean;
+    experimentalAddHeaderAnchorIds?: 'mintlify';
     experimentalHideDefaultLocale?: boolean;
     experimentalFlattenJsonFiles?: boolean;
     baseDomain?: string;

package/dist/utils/addExplicitAnchorIds.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Represents a heading with its position and metadata
+ */
+export interface HeadingInfo {
+    text: string;
+    level: number;
+    slug: string;
+    position: number;
+}
+/**
+ * Extracts heading information from content (read-only, no modifications)
+ */
+export declare function extractHeadingInfo(mdxContent: string): HeadingInfo[];
+/**
+ * Applies anchor IDs to translated content based on source heading mapping
+ */
+export declare function addExplicitAnchorIds(translatedContent: string, sourceHeadingMap: HeadingInfo[], settings?: any, sourcePath?: string, translatedPath?: string): {
+    content: string;
+    hasChanges: boolean;
+    addedIds: Array<{
+        heading: string;
+        id: string;
+    }>;
+};

package/dist/utils/addExplicitAnchorIds.js

@@ -0,0 +1,263 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMdx from 'remark-mdx';
+import remarkFrontmatter from 'remark-frontmatter';
+import remarkStringify from 'remark-stringify';
+import { visit } from 'unist-util-visit';
+import { logErrorAndExit } from '../console/logging.js';
+/**
+ * Generates a slug from heading text
+ */
+function generateSlug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s-]/g, '') // Remove special chars except spaces and hyphens
+        .trim()
+        .replace(/\s+/g, '-') // Replace spaces with hyphens
+        .replace(/-+/g, '-') // Replace multiple hyphens with single hyphen
+        .replace(/^-|-$/g, ''); // Remove leading/trailing hyphens
+}
+/**
+ * Extracts text content from heading nodes
+ */
+function extractHeadingText(heading) {
+    let text = '';
+    visit(heading, ['text', 'inlineCode'], (node) => {
+        if ('value' in node && typeof node.value === 'string') {
+            text += node.value;
+        }
+    });
+    return text;
+}
+/**
+ * Checks if a heading is already wrapped in a div with id
+ */
+function hasExplicitId(heading, ast) {
+    const lastChild = heading.children[heading.children.length - 1];
+    if (lastChild?.type === 'text') {
+        return /(\{#[^}]+\}|\[[^\]]+\])$/.test(lastChild.value);
+    }
+    return false;
+}
+/**
+ * Extracts heading information from content (read-only, no modifications)
+ */
+export function extractHeadingInfo(mdxContent) {
+    const headings = [];
+    // Parse the MDX content into an AST
+    let processedAst;
+    try {
+        const parseProcessor = unified()
+            .use(remarkParse)
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        const ast = parseProcessor.parse(mdxContent);
+        processedAst = parseProcessor.runSync(ast);
+    }
+    catch (error) {
+        console.warn(`Failed to parse MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+    let position = 0;
+    visit(processedAst, 'heading', (heading) => {
+        const headingText = extractHeadingText(heading);
+        if (headingText) {
+            const slug = generateSlug(headingText);
+            headings.push({
+                text: headingText,
+                level: heading.depth,
+                slug,
+                position: position++,
+            });
+        }
+    });
+    return headings;
+}
+/**
+ * Applies anchor IDs to translated content based on source heading mapping
+ */
+export function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sourcePath, translatedPath) {
+    const addedIds = [];
+    const useDivWrapping = settings?.options?.experimentalAddHeaderAnchorIds === 'mintlify';
+    // Extract headings from translated content
+    const translatedHeadings = extractHeadingInfo(translatedContent);
+    // Pre-processing validation: check if header counts match
+    if (sourceHeadingMap.length !== translatedHeadings.length) {
+        const sourceFile = sourcePath
+            ? `Source file: ${sourcePath}`
+            : 'Source file';
+        const translatedFile = translatedPath
+            ? `translated file: ${translatedPath}`
+            : 'translated file';
+        logErrorAndExit(`Header count mismatch detected! ${sourceFile} has ${sourceHeadingMap.length} headers but ${translatedFile} has ${translatedHeadings.length} headers. ` +
+            `This likely means your source file was edited after translation was requested, causing a mismatch between ` +
+            `the number of headers in your source file vs the translated file. Please re-translate this file to resolve the issue.`);
+    }
+    // Create ID mapping based on positional matching
+    const idMappings = new Map();
+    sourceHeadingMap.forEach((sourceHeading, index) => {
+        const translatedHeading = translatedHeadings[index];
+        // Match by position and level for safety
+        if (translatedHeading && translatedHeading.level === sourceHeading.level) {
+            idMappings.set(index, sourceHeading.slug);
+            addedIds.push({
+                heading: translatedHeading.text,
+                id: sourceHeading.slug,
+            });
+        }
+    });
+    if (idMappings.size === 0) {
+        return {
+            content: translatedContent,
+            hasChanges: false,
+            addedIds: [],
+        };
+    }
+    // Apply IDs to translated content
+    let content;
+    if (useDivWrapping) {
+        content = applyDivWrappedIds(translatedContent, translatedHeadings, idMappings);
+    }
+    else {
+        content = applyInlineIds(translatedContent, idMappings);
+    }
+    return {
+        content,
+        hasChanges: addedIds.length > 0,
+        addedIds,
+    };
+}
+/**
+ * Adds inline {#id} syntax to headings (standard markdown approach)
+ */
+function applyInlineIds(translatedContent, idMappings) {
+    // Parse the translated content
+    let processedAst;
+    try {
+        const parseProcessor = unified()
+            .use(remarkParse)
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        const ast = parseProcessor.parse(translatedContent);
+        processedAst = parseProcessor.runSync(ast);
+    }
+    catch (error) {
+        console.warn(`Failed to parse translated MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return translatedContent;
+    }
+    // Apply IDs to headings based on position
+    let headingIndex = 0;
+    visit(processedAst, 'heading', (heading) => {
+        const id = idMappings.get(headingIndex);
+        if (id) {
+            // Skip if heading already has explicit ID
+            if (hasExplicitId(heading, processedAst)) {
+                headingIndex++;
+                return;
+            }
+            // Add the ID to the heading
+            const lastChild = heading.children[heading.children.length - 1];
+            if (lastChild?.type === 'text') {
+                lastChild.value += ` {#${id}}`;
+            }
+            else {
+                // If last child is not text, add a new text node
+                heading.children.push({
+                    type: 'text',
+                    value: ` {#${id}}`,
+                });
+            }
+        }
+        headingIndex++;
+    });
+    // Convert the modified AST back to MDX string
+    try {
+        const stringifyProcessor = unified()
+            .use(remarkStringify, {
+            bullet: '-',
+            emphasis: '_',
+            strong: '*',
+            rule: '-',
+            ruleRepetition: 3,
+            ruleSpaces: false,
+            handlers: {
+                // Custom handler to prevent escaping of {#id} syntax
+                text(node) {
+                    return node.value;
+                },
+            },
+        })
+            .use(remarkFrontmatter, ['yaml', 'toml'])
+            .use(remarkMdx);
+        let content = stringifyProcessor.stringify(processedAst);
+        // Handle newline formatting to match original input
+        if (content.endsWith('\n') && !translatedContent.endsWith('\n')) {
+            content = content.slice(0, -1);
+        }
+        // Preserve leading newlines from original content
+        if (translatedContent.startsWith('\n') && !content.startsWith('\n')) {
+            content = '\n' + content;
+        }
+        return content;
+    }
+    catch (error) {
+        console.warn(`Failed to stringify translated MDX content: ${error instanceof Error ? error.message : String(error)}`);
+        return translatedContent;
+    }
+}
+/**
+ * Wraps headings in divs with IDs (Mintlify approach)
+ */
+function applyDivWrappedIds(translatedContent, translatedHeadings, idMappings) {
+    // Extract all heading lines from the translated markdown
+    const lines = translatedContent.split('\n');
+    const headingLines = [];
+    lines.forEach((line, index) => {
+        const headingMatch = line.match(/^(#{1,6})\s+(.+)$/);
+        if (headingMatch) {
+            const level = headingMatch[1].length;
+            headingLines.push({ line, level, index });
+        }
+    });
+    // Use string-based approach to wrap headings in divs
+    let content = translatedContent;
+    const headingsToWrap = [];
+    // Match translated headings with their corresponding lines by position and level
+    translatedHeadings.forEach((heading, position) => {
+        const id = idMappings.get(position);
+        if (id) {
+            // Find the corresponding original line for this heading
+            const matchingLine = headingLines.find((hl) => {
+                // Extract clean text from the original line for comparison
+                const lineCleanText = hl.line.replace(/^#{1,6}\s+/, '').trim();
+                // Create a version without markdown formatting for comparison
+                const cleanLineText = lineCleanText
+                    .replace(/\*\*(.*?)\*\*/g, '$1') // Remove bold
+                    .replace(/\*(.*?)\*/g, '$1') // Remove italic
+                    .replace(/`(.*?)`/g, '$1') // Remove inline code
+                    .replace(/\[(.*?)\]\(.*?\)/g, '$1') // Remove links, keep text
+                    .trim();
+                return cleanLineText === heading.text && hl.level === heading.level;
+            });
+            if (matchingLine) {
+                headingsToWrap.push({
+                    originalLine: matchingLine.line,
+                    id,
+                });
+            }
+        }
+    });
+    if (headingsToWrap.length > 0) {
+        // Process headings from longest to shortest original line to avoid partial matches
+        const sortedHeadings = headingsToWrap.sort((a, b) => b.originalLine.length - a.originalLine.length);
+        for (const heading of sortedHeadings) {
+            // Escape the original line for use in regex
+            const escapedLine = heading.originalLine.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const headingPattern = new RegExp(`^${escapedLine}\\s*$`, 'gm');
+            content = content.replace(headingPattern, (match) => {
+                return `<div id="${heading.id}">\n  ${match.trim()}\n</div>\n`;
+            });
+        }
+    }
+    return content;
+}

package/dist/utils/localizeStaticUrls.js

@@ -87,6 +87,10 @@ export default async function localizeStaticUrls(settings, targetLocales) {
  * Determines if a URL should be processed based on pattern matching
  */
 function shouldProcessUrl(originalUrl, patternHead, targetLocale, defaultLocale, baseDomain) {
+    // Check fragment-only URLs like "#id-name"
+    if (/^\s*#/.test(originalUrl)) {
+        return false;
+    }
     const patternWithoutSlash = patternHead.replace(/\/$/, '');
     // Handle absolute URLs with baseDomain
     let urlToCheck = originalUrl;

package/dist/utils/processAnchorIds.d.ts

@@ -0,0 +1,6 @@
+import { Settings } from '../types/index.js';
+/**
+ * Processes all translated MD/MDX files to add explicit anchor IDs
+ * This preserves navigation links when headings are translated
+ */
+export default function processAnchorIds(settings: Settings): Promise<void>;

package/dist/utils/processAnchorIds.js

@@ -0,0 +1,43 @@
+import { addExplicitAnchorIds, extractHeadingInfo, } from './addExplicitAnchorIds.js';
+import { readFile } from '../fs/findFilepath.js';
+import { createFileMapping } from '../formats/files/fileMapping.js';
+import * as fs from 'fs';
+/**
+ * Processes all translated MD/MDX files to add explicit anchor IDs
+ * This preserves navigation links when headings are translated
+ */
+export default async function processAnchorIds(settings) {
+    if (!settings.files)
+        return;
+    const { resolvedPaths, placeholderPaths, transformPaths } = settings.files;
+    const fileMapping = createFileMapping(resolvedPaths, placeholderPaths, transformPaths, settings.locales, settings.defaultLocale);
+    // Process each locale's translated files
+    const processPromises = Object.entries(fileMapping)
+        .filter(([locale, filesMap]) => locale !== settings.defaultLocale) // Skip default locale
+        .map(async ([locale, filesMap]) => {
+        // Get all translated files that are md or mdx
+        const translatedFiles = Object.values(filesMap).filter((path) => path && (path.endsWith('.md') || path.endsWith('.mdx')));
+        for (const translatedPath of translatedFiles) {
+            try {
+                // Find the corresponding source file
+                const sourcePath = Object.keys(filesMap).find((key) => filesMap[key] === translatedPath);
+                if (!sourcePath) {
+                    continue;
+                }
+                // Extract heading info from source file
+                const sourceContent = readFile(sourcePath);
+                const sourceHeadingMap = extractHeadingInfo(sourceContent);
+                // Read translated file and apply anchor IDs
+                const translatedContent = readFile(translatedPath);
+                const result = addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sourcePath, translatedPath);
+                if (result.hasChanges) {
+                    fs.writeFileSync(translatedPath, result.content, 'utf8');
+                }
+            }
+            catch (error) {
+                console.warn(`Failed to process IDs for ${translatedPath}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    });
+    await Promise.all(processPromises);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gtx-cli",
-  "version": "2.1.9",
+  "version": "2.1.10",
   "main": "dist/index.js",
   "bin": "dist/main.js",
   "files": [