gt 2.17.1 → 2.17.3

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # gtx-cli
 
+## 2.17.3
+
+### Patch Changes
+
+- [#2221](https://github.com/generaltranslation/gt/pull/2221) [`cadd04a`](https://github.com/generaltranslation/gt/commit/cadd04a07d73fd6090c3f72a199f03e443b5db10) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Fix custom heading IDs (`## Heading {#id}`) being dropped or misapplied in translated MD/MDX.
+
+  `{#id}` is not valid MDX — remark-mdx hands it to acorn as an expression — so files
+  using Mintlify's custom heading ID syntax failed validation and were skipped
+  entirely. Parsing now tolerates the syntax, so `skipFileValidation` is no longer
+  needed to translate those files.
+
+  Anchor IDs are also applied far more reliably:
+  - Headings are located by parser line positions instead of by matching heading
+    text, so indentation (headings nested in `<Tabs>`, `<Steps>`, `<Accordion>`),
+    inline JSX, escaped characters and repeated heading text no longer cause a
+    heading to be skipped or an ID to land on the wrong heading.
+  - Repeated headings now get unique IDs (`slug`, `slug-2`, `slug-3`) matching how
+    Mintlify disambiguates them, instead of emitting the same ID several times.
+  - Source and translated files are now read with the same extractor. Previously a
+    source using `{#id}` fell back to line scanning while its translation used the
+    AST, so the two heading lists could disagree and shift every ID after the first
+    nested heading.
+  - In `experimentalAddHeaderAnchorIds: 'mintlify'` mode, an author-written `{#id}`
+    is carried into the translation in Mintlify's native inline syntax rather than
+    being replaced by a `<div id>` wrapper. Wrappers are still used for IDs the CLI
+    derives from heading text.
+  - Applying an anchor no longer re-stringifies the whole document, so it no longer
+    HTML-escapes unrelated heading text or reformats the file.
+  - An existing wrapper is recognized from the parsed tree rather than by matching
+    the tag's text, so extra attributes, single quotes, a multi-line tag or a
+    non-`div` element no longer cause a second wrapper to be nested inside the first.
+  - An inline anchor is inserted before a heading's closing `##` sequence instead of
+    after it, which previously turned the closing hashes into visible heading text.
+
+  Anchor processing now runs after the other MD/MDX post-processing passes, which
+  re-indent headings nested in JSX when they stringify.
+
+- Updated dependencies []:
+  - generaltranslation@9.1.10
+  - @generaltranslation/python-extractor@0.2.43
+  - @generaltranslation/supported-locales@2.1.23
+  - @generaltranslation/vue-extractor@0.1.3
+
+## 2.17.2
+
+### Patch Changes
+
+- Updated dependencies []:
+  - generaltranslation@9.1.9
+  - @generaltranslation/python-extractor@0.2.42
+  - @generaltranslation/supported-locales@2.1.22
+  - @generaltranslation/vue-extractor@0.1.2
+
 ## 2.17.1
 
 ### Patch Changes

package/dist/cli/commands/translate.js

@@ -49,8 +49,8 @@ async function postProcessTranslations(settings, includeFiles) {
 		const nonDefaultLocales = settings.locales.filter((locale) => locale !== settings.defaultLocale);
 		if (nonDefaultLocales.length > 0) await localizeRelativeAssets(settings, nonDefaultLocales, postProcessIncludes);
 	}
-	if (settings.options?.experimentalLocalizeStaticUrls || settings.options?.experimentalAddHeaderAnchorIds) await processAnchorIds(settings, postProcessIncludes);
 	if (settings.options?.experimentalLocalizeStaticImports) await localizeStaticImports(settings, postProcessIncludes);
+	if (settings.options?.experimentalLocalizeStaticUrls || settings.options?.experimentalAddHeaderAnchorIds) await processAnchorIds(settings, postProcessIncludes);
 	if (settings.options?.experimentalFlattenJsonFiles) await flattenJsonFiles(settings, postProcessIncludes);
 	if (settings.options?.copyFiles) await copyFile(settings);
 	persistPostProcessHashes(settings, postProcessIncludes, getDownloadedMeta());

package/dist/cli/commands/translate.js.map

@@ -1 +1 @@
-{"version":3,"file":"translate.js","names":[],"sources":["../../../src/cli/commands/translate.ts"],"sourcesContent":["import { EnqueueFilesResult } from 'generaltranslation/types';\nimport { TranslateFlags } from '../../types/index.js';\nimport { Settings } from '../../types/index.js';\nimport {\n  FileTranslationData,\n  runDownloadWorkflow,\n} from '../../workflows/download.js';\nimport { createFileMapping } from '../../formats/files/fileMapping.js';\nimport copyFile from '../../fs/copyFile.js';\nimport flattenJsonFiles from '../../utils/flattenJsonFiles.js';\nimport localizeStaticUrls from '../../utils/localizeStaticUrls.js';\nimport localizeRelativeAssets from '../../utils/localizeRelativeAssets.js';\nimport processAnchorIds from '../../utils/processAnchorIds.js';\nimport localizeStaticImports from '../../utils/localizeStaticImports.js';\nimport { postprocessMintlify } from '../../formats/files/postprocess/mintlify.js';\nimport { BranchData } from '../../types/branch.js';\nimport { getDownloadedMeta } from '../../state/recentDownloads.js';\nimport { persistPostProcessHashes } from '../../utils/persistPostprocessHashes.js';\nimport { runPublishWorkflow } from '../../workflows/publish.js';\nimport { SUPPORTED_FILE_EXTENSIONS } from '../../formats/files/supportedFiles.js';\nimport { hasNonIdentityFileFormatTransformForType } from '../../formats/files/transformFormat.js';\nimport { getRelative } from '../../fs/findFilepath.js';\nimport type { InlineLibrary } from '../../types/libraries.js';\n\n// Downloads translations that were completed\nexport async function handleTranslate(\n  options: TranslateFlags,\n  settings: Settings,\n  fileVersionData: FileTranslationData | undefined,\n  jobData: EnqueueFilesResult | undefined,\n  branchData: BranchData | undefined,\n  publishMap?: Map<string, boolean>,\n  inlineLibrary?: InlineLibrary\n) {\n  if (fileVersionData) {\n    const {\n      resolvedPaths,\n      placeholderPaths,\n      transformPaths,\n      transformFormats,\n    } = settings.files;\n\n    const fileMapping = createFileMapping(\n      resolvedPaths,\n      placeholderPaths,\n      transformPaths,\n      transformFormats,\n      settings.locales,\n      settings.defaultLocale\n    );\n    // Check for remaining translations\n    await runDownloadWorkflow({\n      fileVersionData: fileVersionData,\n      jobData: jobData,\n      branchData: branchData,\n      locales: settings.locales,\n      timeoutDuration: options.timeout,\n      resolveOutputPath: (sourcePath, locale) =>\n        fileMapping[locale]?.[sourcePath] ?? null,\n      options: settings,\n      inlineLibrary,\n      forceRetranslation: options.force,\n      forceDownload: options.forceDownload || options.force, // if force is true should also force download\n    });\n\n    // Publish/unpublish files after translations are downloaded\n    if (publishMap && branchData?.currentBranch.id) {\n      const files = Object.entries(fileVersionData).map(([fileId, data]) => ({\n        fileId,\n        versionId: data.versionId,\n        fileName: data.fileName,\n      }));\n      await runPublishWorkflow(\n        files,\n        publishMap,\n        branchData.currentBranch.id,\n        settings\n      );\n    }\n  }\n}\n\nexport async function postProcessTranslations(\n  settings: Settings,\n  includeFiles?: Set<string>\n) {\n  const postProcessIncludes = filterPostProcessIncludesForFormatTransforms(\n    settings,\n    includeFiles\n  );\n  if (includeFiles && postProcessIncludes?.size === 0) return;\n\n  await postprocessMintlify(settings, postProcessIncludes);\n\n  // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales\n  // Default locale is processed earlier in the flow in base.ts\n  if (settings.options?.experimentalLocalizeStaticUrls) {\n    const nonDefaultLocales = settings.locales.filter(\n      (locale) => locale !== settings.defaultLocale\n    );\n    if (nonDefaultLocales.length > 0) {\n      await localizeStaticUrls(\n        settings,\n        nonDefaultLocales,\n        postProcessIncludes\n      );\n    }\n  }\n\n  // Rewrite relative asset URLs in translated md/mdx files\n  if (settings.options?.experimentalLocalizeRelativeAssets) {\n    const nonDefaultLocales = settings.locales.filter(\n      (locale) => locale !== settings.defaultLocale\n    );\n    if (nonDefaultLocales.length > 0) {\n      await localizeRelativeAssets(\n        settings,\n        nonDefaultLocales,\n        postProcessIncludes\n      );\n    }\n  }\n\n  const shouldProcessAnchorIds =\n    settings.options?.experimentalLocalizeStaticUrls ||\n    settings.options?.experimentalAddHeaderAnchorIds;\n\n  // Add explicit anchor IDs to translated MDX/MD files to preserve navigation\n  // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'\n  if (shouldProcessAnchorIds) {\n    await processAnchorIds(settings, postProcessIncludes);\n  }\n\n  // Localize static imports (import Snippet from /snippets/file.mdx -> import Snippet from /snippets/[locale]/file.mdx)\n  if (settings.options?.experimentalLocalizeStaticImports) {\n    await localizeStaticImports(settings, postProcessIncludes);\n  }\n\n  // Flatten json files into a single file\n  if (settings.options?.experimentalFlattenJsonFiles) {\n    await flattenJsonFiles(settings, postProcessIncludes);\n  }\n\n  // Copy files to the target locale\n  if (settings.options?.copyFiles) {\n    await copyFile(settings);\n  }\n\n  // Record postprocessed content hashes for newly downloaded files\n  persistPostProcessHashes(settings, postProcessIncludes, getDownloadedMeta());\n}\n\n/**\n * Exclude only outputs whose source file was translated into a different format.\n * @param settings - The settings for the project\n * @param includeFiles - The files to include in the post-processing\n * @returns The files to exclude in the post-processing\n */\nfunction filterPostProcessIncludesForFormatTransforms(\n  settings: Settings,\n  includeFiles?: Set<string>\n): Set<string> | undefined {\n  if (!includeFiles) return includeFiles;\n\n  const transformedSourcePaths = new Set<string>();\n  for (const fileType of SUPPORTED_FILE_EXTENSIONS) {\n    if (!hasNonIdentityFileFormatTransformForType(settings, fileType)) continue;\n\n    for (const sourcePath of settings.files.resolvedPaths[fileType] || []) {\n      transformedSourcePaths.add(getRelative(sourcePath));\n    }\n  }\n  if (transformedSourcePaths.size === 0) return includeFiles;\n\n  const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } =\n    settings.files;\n  const fileMapping = createFileMapping(\n    resolvedPaths,\n    placeholderPaths,\n    transformPaths,\n    transformFormats,\n    settings.locales,\n    settings.defaultLocale\n  );\n\n  const transformedOutputPaths = new Set<string>();\n  for (const localeMapping of Object.values(fileMapping)) {\n    for (const [sourcePath, outputPath] of Object.entries(localeMapping)) {\n      if (transformedSourcePaths.has(sourcePath)) {\n        transformedOutputPaths.add(outputPath);\n      }\n    }\n  }\n\n  return new Set(\n    [...includeFiles].filter(\n      (filePath) => !transformedOutputPaths.has(filePath)\n    )\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,eAAsB,gBACpB,SACA,UACA,iBACA,SACA,YACA,YACA,eACA;AACA,KAAI,iBAAiB;EACnB,MAAM,EACJ,eACA,kBACA,gBACA,qBACE,SAAS;EAEb,MAAM,cAAc,kBAClB,eACA,kBACA,gBACA,kBACA,SAAS,SACT,SAAS,cACV;AAED,QAAM,oBAAoB;GACP;GACR;GACG;GACZ,SAAS,SAAS;GAClB,iBAAiB,QAAQ;GACzB,oBAAoB,YAAY,WAC9B,YAAY,UAAU,eAAe;GACvC,SAAS;GACT;GACA,oBAAoB,QAAQ;GAC5B,eAAe,QAAQ,iBAAiB,QAAQ;GACjD,CAAC;AAGF,MAAI,cAAc,YAAY,cAAc,GAM1C,OAAM,mBALQ,OAAO,QAAQ,gBAAgB,CAAC,KAAK,CAAC,QAAQ,WAAW;GACrE;GACA,WAAW,KAAK;GAChB,UAAU,KAAK;GAChB,EAEM,EACL,YACA,WAAW,cAAc,IACzB,SACD;;;AAKP,eAAsB,wBACpB,UACA,cACA;CACA,MAAM,sBAAsB,6CAC1B,UACA,aACD;AACD,KAAI,gBAAgB,qBAAqB,SAAS,EAAG;AAErD,OAAM,oBAAoB,UAAU,oBAAoB;AAIxD,KAAI,SAAS,SAAS,gCAAgC;EACpD,MAAM,oBAAoB,SAAS,QAAQ,QACxC,WAAW,WAAW,SAAS,cACjC;AACD,MAAI,kBAAkB,SAAS,EAC7B,OAAM,mBACJ,UACA,mBACA,oBACD;;AAKL,KAAI,SAAS,SAAS,oCAAoC;EACxD,MAAM,oBAAoB,SAAS,QAAQ,QACxC,WAAW,WAAW,SAAS,cACjC;AACD,MAAI,kBAAkB,SAAS,EAC7B,OAAM,uBACJ,UACA,mBACA,oBACD;;AAUL,KALE,SAAS,SAAS,kCAClB,SAAS,SAAS,+BAKlB,OAAM,iBAAiB,UAAU,oBAAoB;AAIvD,KAAI,SAAS,SAAS,kCACpB,OAAM,sBAAsB,UAAU,oBAAoB;AAI5D,KAAI,SAAS,SAAS,6BACpB,OAAM,iBAAiB,UAAU,oBAAoB;AAIvD,KAAI,SAAS,SAAS,UACpB,OAAM,SAAS,SAAS;AAI1B,0BAAyB,UAAU,qBAAqB,mBAAmB,CAAC;;;;;;;;AAS9E,SAAS,6CACP,UACA,cACyB;AACzB,KAAI,CAAC,aAAc,QAAO;CAE1B,MAAM,yCAAyB,IAAI,KAAa;AAChD,MAAK,MAAM,YAAY,2BAA2B;AAChD,MAAI,CAAC,yCAAyC,UAAU,SAAS,CAAE;AAEnE,OAAK,MAAM,cAAc,SAAS,MAAM,cAAc,aAAa,EAAE,CACnE,wBAAuB,IAAI,YAAY,WAAW,CAAC;;AAGvD,KAAI,uBAAuB,SAAS,EAAG,QAAO;CAE9C,MAAM,EAAE,eAAe,kBAAkB,gBAAgB,qBACvD,SAAS;CACX,MAAM,cAAc,kBAClB,eACA,kBACA,gBACA,kBACA,SAAS,SACT,SAAS,cACV;CAED,MAAM,yCAAyB,IAAI,KAAa;AAChD,MAAK,MAAM,iBAAiB,OAAO,OAAO,YAAY,CACpD,MAAK,MAAM,CAAC,YAAY,eAAe,OAAO,QAAQ,cAAc,CAClE,KAAI,uBAAuB,IAAI,WAAW,CACxC,wBAAuB,IAAI,WAAW;AAK5C,QAAO,IAAI,IACT,CAAC,GAAG,aAAa,CAAC,QACf,aAAa,CAAC,uBAAuB,IAAI,SAAS,CACpD,CACF"}
+{"version":3,"file":"translate.js","names":[],"sources":["../../../src/cli/commands/translate.ts"],"sourcesContent":["import { EnqueueFilesResult } from 'generaltranslation/types';\nimport { TranslateFlags } from '../../types/index.js';\nimport { Settings } from '../../types/index.js';\nimport {\n  FileTranslationData,\n  runDownloadWorkflow,\n} from '../../workflows/download.js';\nimport { createFileMapping } from '../../formats/files/fileMapping.js';\nimport copyFile from '../../fs/copyFile.js';\nimport flattenJsonFiles from '../../utils/flattenJsonFiles.js';\nimport localizeStaticUrls from '../../utils/localizeStaticUrls.js';\nimport localizeRelativeAssets from '../../utils/localizeRelativeAssets.js';\nimport processAnchorIds from '../../utils/processAnchorIds.js';\nimport localizeStaticImports from '../../utils/localizeStaticImports.js';\nimport { postprocessMintlify } from '../../formats/files/postprocess/mintlify.js';\nimport { BranchData } from '../../types/branch.js';\nimport { getDownloadedMeta } from '../../state/recentDownloads.js';\nimport { persistPostProcessHashes } from '../../utils/persistPostprocessHashes.js';\nimport { runPublishWorkflow } from '../../workflows/publish.js';\nimport { SUPPORTED_FILE_EXTENSIONS } from '../../formats/files/supportedFiles.js';\nimport { hasNonIdentityFileFormatTransformForType } from '../../formats/files/transformFormat.js';\nimport { getRelative } from '../../fs/findFilepath.js';\nimport type { InlineLibrary } from '../../types/libraries.js';\n\n// Downloads translations that were completed\nexport async function handleTranslate(\n  options: TranslateFlags,\n  settings: Settings,\n  fileVersionData: FileTranslationData | undefined,\n  jobData: EnqueueFilesResult | undefined,\n  branchData: BranchData | undefined,\n  publishMap?: Map<string, boolean>,\n  inlineLibrary?: InlineLibrary\n) {\n  if (fileVersionData) {\n    const {\n      resolvedPaths,\n      placeholderPaths,\n      transformPaths,\n      transformFormats,\n    } = settings.files;\n\n    const fileMapping = createFileMapping(\n      resolvedPaths,\n      placeholderPaths,\n      transformPaths,\n      transformFormats,\n      settings.locales,\n      settings.defaultLocale\n    );\n    // Check for remaining translations\n    await runDownloadWorkflow({\n      fileVersionData: fileVersionData,\n      jobData: jobData,\n      branchData: branchData,\n      locales: settings.locales,\n      timeoutDuration: options.timeout,\n      resolveOutputPath: (sourcePath, locale) =>\n        fileMapping[locale]?.[sourcePath] ?? null,\n      options: settings,\n      inlineLibrary,\n      forceRetranslation: options.force,\n      forceDownload: options.forceDownload || options.force, // if force is true should also force download\n    });\n\n    // Publish/unpublish files after translations are downloaded\n    if (publishMap && branchData?.currentBranch.id) {\n      const files = Object.entries(fileVersionData).map(([fileId, data]) => ({\n        fileId,\n        versionId: data.versionId,\n        fileName: data.fileName,\n      }));\n      await runPublishWorkflow(\n        files,\n        publishMap,\n        branchData.currentBranch.id,\n        settings\n      );\n    }\n  }\n}\n\nexport async function postProcessTranslations(\n  settings: Settings,\n  includeFiles?: Set<string>\n) {\n  const postProcessIncludes = filterPostProcessIncludesForFormatTransforms(\n    settings,\n    includeFiles\n  );\n  if (includeFiles && postProcessIncludes?.size === 0) return;\n\n  await postprocessMintlify(settings, postProcessIncludes);\n\n  // Localize static urls (/docs -> /[locale]/docs) and preserve anchor IDs for non-default locales\n  // Default locale is processed earlier in the flow in base.ts\n  if (settings.options?.experimentalLocalizeStaticUrls) {\n    const nonDefaultLocales = settings.locales.filter(\n      (locale) => locale !== settings.defaultLocale\n    );\n    if (nonDefaultLocales.length > 0) {\n      await localizeStaticUrls(\n        settings,\n        nonDefaultLocales,\n        postProcessIncludes\n      );\n    }\n  }\n\n  // Rewrite relative asset URLs in translated md/mdx files\n  if (settings.options?.experimentalLocalizeRelativeAssets) {\n    const nonDefaultLocales = settings.locales.filter(\n      (locale) => locale !== settings.defaultLocale\n    );\n    if (nonDefaultLocales.length > 0) {\n      await localizeRelativeAssets(\n        settings,\n        nonDefaultLocales,\n        postProcessIncludes\n      );\n    }\n  }\n\n  // Localize static imports (import Snippet from /snippets/file.mdx -> import Snippet from /snippets/[locale]/file.mdx)\n  if (settings.options?.experimentalLocalizeStaticImports) {\n    await localizeStaticImports(settings, postProcessIncludes);\n  }\n\n  const shouldProcessAnchorIds =\n    settings.options?.experimentalLocalizeStaticUrls ||\n    settings.options?.experimentalAddHeaderAnchorIds;\n\n  // Add explicit anchor IDs to translated MDX/MD files to preserve navigation.\n  // Uses inline {#id} format by default, or div wrapping if experimentalAddHeaderAnchorIds is 'mintlify'.\n  //\n  // Runs last of the md/mdx passes: the others re-stringify the document, which\n  // re-indents headings nested in JSX and would otherwise move them out from\n  // under the anchors placed here.\n  if (shouldProcessAnchorIds) {\n    await processAnchorIds(settings, postProcessIncludes);\n  }\n\n  // Flatten json files into a single file\n  if (settings.options?.experimentalFlattenJsonFiles) {\n    await flattenJsonFiles(settings, postProcessIncludes);\n  }\n\n  // Copy files to the target locale\n  if (settings.options?.copyFiles) {\n    await copyFile(settings);\n  }\n\n  // Record postprocessed content hashes for newly downloaded files\n  persistPostProcessHashes(settings, postProcessIncludes, getDownloadedMeta());\n}\n\n/**\n * Exclude only outputs whose source file was translated into a different format.\n * @param settings - The settings for the project\n * @param includeFiles - The files to include in the post-processing\n * @returns The files to exclude in the post-processing\n */\nfunction filterPostProcessIncludesForFormatTransforms(\n  settings: Settings,\n  includeFiles?: Set<string>\n): Set<string> | undefined {\n  if (!includeFiles) return includeFiles;\n\n  const transformedSourcePaths = new Set<string>();\n  for (const fileType of SUPPORTED_FILE_EXTENSIONS) {\n    if (!hasNonIdentityFileFormatTransformForType(settings, fileType)) continue;\n\n    for (const sourcePath of settings.files.resolvedPaths[fileType] || []) {\n      transformedSourcePaths.add(getRelative(sourcePath));\n    }\n  }\n  if (transformedSourcePaths.size === 0) return includeFiles;\n\n  const { resolvedPaths, placeholderPaths, transformPaths, transformFormats } =\n    settings.files;\n  const fileMapping = createFileMapping(\n    resolvedPaths,\n    placeholderPaths,\n    transformPaths,\n    transformFormats,\n    settings.locales,\n    settings.defaultLocale\n  );\n\n  const transformedOutputPaths = new Set<string>();\n  for (const localeMapping of Object.values(fileMapping)) {\n    for (const [sourcePath, outputPath] of Object.entries(localeMapping)) {\n      if (transformedSourcePaths.has(sourcePath)) {\n        transformedOutputPaths.add(outputPath);\n      }\n    }\n  }\n\n  return new Set(\n    [...includeFiles].filter(\n      (filePath) => !transformedOutputPaths.has(filePath)\n    )\n  );\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAyBA,eAAsB,gBACpB,SACA,UACA,iBACA,SACA,YACA,YACA,eACA;AACA,KAAI,iBAAiB;EACnB,MAAM,EACJ,eACA,kBACA,gBACA,qBACE,SAAS;EAEb,MAAM,cAAc,kBAClB,eACA,kBACA,gBACA,kBACA,SAAS,SACT,SAAS,cACV;AAED,QAAM,oBAAoB;GACP;GACR;GACG;GACZ,SAAS,SAAS;GAClB,iBAAiB,QAAQ;GACzB,oBAAoB,YAAY,WAC9B,YAAY,UAAU,eAAe;GACvC,SAAS;GACT;GACA,oBAAoB,QAAQ;GAC5B,eAAe,QAAQ,iBAAiB,QAAQ;GACjD,CAAC;AAGF,MAAI,cAAc,YAAY,cAAc,GAM1C,OAAM,mBALQ,OAAO,QAAQ,gBAAgB,CAAC,KAAK,CAAC,QAAQ,WAAW;GACrE;GACA,WAAW,KAAK;GAChB,UAAU,KAAK;GAChB,EAEM,EACL,YACA,WAAW,cAAc,IACzB,SACD;;;AAKP,eAAsB,wBACpB,UACA,cACA;CACA,MAAM,sBAAsB,6CAC1B,UACA,aACD;AACD,KAAI,gBAAgB,qBAAqB,SAAS,EAAG;AAErD,OAAM,oBAAoB,UAAU,oBAAoB;AAIxD,KAAI,SAAS,SAAS,gCAAgC;EACpD,MAAM,oBAAoB,SAAS,QAAQ,QACxC,WAAW,WAAW,SAAS,cACjC;AACD,MAAI,kBAAkB,SAAS,EAC7B,OAAM,mBACJ,UACA,mBACA,oBACD;;AAKL,KAAI,SAAS,SAAS,oCAAoC;EACxD,MAAM,oBAAoB,SAAS,QAAQ,QACxC,WAAW,WAAW,SAAS,cACjC;AACD,MAAI,kBAAkB,SAAS,EAC7B,OAAM,uBACJ,UACA,mBACA,oBACD;;AAKL,KAAI,SAAS,SAAS,kCACpB,OAAM,sBAAsB,UAAU,oBAAoB;AAa5D,KATE,SAAS,SAAS,kCAClB,SAAS,SAAS,+BASlB,OAAM,iBAAiB,UAAU,oBAAoB;AAIvD,KAAI,SAAS,SAAS,6BACpB,OAAM,iBAAiB,UAAU,oBAAoB;AAIvD,KAAI,SAAS,SAAS,UACpB,OAAM,SAAS,SAAS;AAI1B,0BAAyB,UAAU,qBAAqB,mBAAmB,CAAC;;;;;;;;AAS9E,SAAS,6CACP,UACA,cACyB;AACzB,KAAI,CAAC,aAAc,QAAO;CAE1B,MAAM,yCAAyB,IAAI,KAAa;AAChD,MAAK,MAAM,YAAY,2BAA2B;AAChD,MAAI,CAAC,yCAAyC,UAAU,SAAS,CAAE;AAEnE,OAAK,MAAM,cAAc,SAAS,MAAM,cAAc,aAAa,EAAE,CACnE,wBAAuB,IAAI,YAAY,WAAW,CAAC;;AAGvD,KAAI,uBAAuB,SAAS,EAAG,QAAO;CAE9C,MAAM,EAAE,eAAe,kBAAkB,gBAAgB,qBACvD,SAAS;CACX,MAAM,cAAc,kBAClB,eACA,kBACA,gBACA,kBACA,SAAS,SACT,SAAS,cACV;CAED,MAAM,yCAAyB,IAAI,KAAa;AAChD,MAAK,MAAM,iBAAiB,OAAO,OAAO,YAAY,CACpD,MAAK,MAAM,CAAC,YAAY,eAAe,OAAO,QAAQ,cAAc,CAClE,KAAI,uBAAuB,IAAI,WAAW,CACxC,wBAAuB,IAAI,WAAW;AAK5C,QAAO,IAAI,IACT,CAAC,GAAG,aAAa,CAAC,QACf,aAAa,CAAC,uBAAuB,IAAI,SAAS,CACpD,CACF"}

package/dist/generated/version.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "2.17.1";
+export declare const PACKAGE_VERSION = "2.17.3";

package/dist/generated/version.js

@@ -1,5 +1,5 @@
 //#region src/generated/version.ts
-const PACKAGE_VERSION = "2.17.1";
+const PACKAGE_VERSION = "2.17.3";
 //#endregion
 export { PACKAGE_VERSION };
 

package/dist/generated/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","names":[],"sources":["../../src/generated/version.ts"],"sourcesContent":["// This file is auto-generated. Do not edit manually.\nexport const PACKAGE_VERSION = '2.17.1';\n"],"mappings":";AACA,MAAa,kBAAkB"}
+{"version":3,"file":"version.js","names":[],"sources":["../../src/generated/version.ts"],"sourcesContent":["// This file is auto-generated. Do not edit manually.\nexport const PACKAGE_VERSION = '2.17.3';\n"],"mappings":";AACA,MAAa,kBAAkB"}

package/dist/utils/addExplicitAnchorIds.d.ts

@@ -2,6 +2,12 @@ import type { AdditionalOptions } from '../types/index.js';
 type AnchorIdSettings = {
     options?: Pick<AdditionalOptions, 'experimentalAddHeaderAnchorIds'>;
 };
+/** A source range on a single line, as 1-based inclusive/exclusive columns. */
+interface ColumnRange {
+    line: number;
+    startColumn: number;
+    endColumn: number;
+}
 /**
  * Represents a heading with its position and metadata
  */
@@ -10,9 +16,23 @@ export interface HeadingInfo {
     level: number;
     slug: string;
     position: number;
+    /** 1-based line the heading starts on. */
+    startLine: number;
+    /** 1-based line the heading ends on (differs from startLine for setext). */
+    endLine: number;
+    /** 1-based column of the heading marker; anything left of it is indentation. */
+    startColumn: number;
+    /** 1-based column just past the text, before any closing `##`; -1 if unknown. */
+    textEndColumn: number;
+    /** `id` attribute of a wrapper element already anchoring this heading. */
+    wrapperId: ColumnRange | null;
+    /** Whether the author wrote an explicit `{#id}`. */
+    explicit: boolean;
 }
 /**
- * Extracts heading information from content (read-only, no modifications)
+ * Extracts heading information from content (read-only, no modifications).
+ * Source and translation are matched by position, so both must parse the same
+ * way — the fallback extractor misses headings nested in JSX.
  */
 export declare function extractHeadingInfo(mdxContent: string): HeadingInfo[];
 /**

package/dist/utils/addExplicitAnchorIds.js

@@ -1,13 +1,11 @@
 import { logger } from "../console/logger.js";
-import { unified } from "unified";
-import remarkParse from "remark-parse";
-import remarkMdx from "remark-mdx";
-import remarkFrontmatter from "remark-frontmatter";
+import { forEachLineOutsideCodeFences, mapLinesOutsideCodeFences, parseMdxTolerantly } from "./mdxAnchorSyntax.js";
 import { visit } from "unist-util-visit";
-import remarkStringify from "remark-stringify";
-import { escapeHtmlInTextNodes, normalizeCJKCharacters } from "gt-remark";
-import { decode } from "html-entities";
 //#region src/utils/addExplicitAnchorIds.ts
+/** An ATX heading line, split into indentation, marker and text. */
+const ATX_HEADING = /^([ \t]*)(#{1,6}[ \t]+)(.*)$/;
+/** A trailing custom anchor ID, in either the plain or MDX-escaped form. */
+const TRAILING_ANCHOR = /\s*(?:\\\{#[^}]+\\\}|\{#[^}]+\})\s*$/;
 /**
 * Generates a slug from heading text
 */
@@ -25,41 +23,31 @@ function extractHeadingText(heading) {
 	return text;
 }
 /**
-* Simple line-by-line heading extractor that skips fenced code blocks.
-* Used as a fallback when MDX parsing fails.
+* Line-by-line heading extractor used when MDX parsing fails outright.
 */
 function extractHeadingsWithFallback(mdxContent) {
 	const headings = [];
-	const lines = mdxContent.split("\n");
 	let position = 0;
-	let inFence = false;
-	let fenceChar = null;
-	for (const line of lines) {
-		const fenceMatch = line.match(/^(\s*)(`{3,}|~{3,})/);
-		if (fenceMatch) {
-			const fenceString = fenceMatch[2];
-			if (!inFence) {
-				inFence = true;
-				fenceChar = fenceString;
-			} else if (fenceChar && fenceString[0] === fenceChar[0] && fenceString.length >= fenceChar.length) {
-				inFence = false;
-				fenceChar = null;
-			}
-			continue;
-		}
-		if (inFence) continue;
-		const headingMatch = line.match(/^(#{1,6})\s+(.*)$/);
-		if (!headingMatch) continue;
-		const hashes = headingMatch[1];
-		const rawText = headingMatch[2];
+	forEachLineOutsideCodeFences(mdxContent, (line, index) => {
+		const headingMatch = line.match(ATX_HEADING);
+		if (!headingMatch) return;
+		const [, indent, marker, rawText] = headingMatch;
 		const { cleanedText, explicitId } = parseHeadingContent(rawText);
-		if (cleanedText || explicitId) headings.push({
+		if (!cleanedText && !explicitId) return;
+		headings.push({
 			text: cleanedText,
-			level: hashes.length,
+			level: marker.trim().length,
 			slug: explicitId ?? generateSlug(cleanedText),
-			position: position++
+			position: position++,
+			startLine: index + 1,
+			endLine: index + 1,
+			startColumn: indent.length + 1,
+			textEndColumn: line.length + 1,
+			wrapperId: null,
+			explicit: explicitId !== void 0
 		});
-	}
+	});
+	assignUniqueSlugs(headings);
 	return headings;
 }
 function parseHeadingContent(text) {
@@ -72,39 +60,72 @@ function parseHeadingContent(text) {
 	};
 }
 /**
-* Checks if a heading is already wrapped in a div with id
+* Suffixes repeated slugs `-2`, `-3`, ... as Mintlify does. Author-written IDs
+* are never renumbered, only reserved.
+*/
+function assignUniqueSlugs(headings) {
+	const used = new Set(headings.filter((heading) => heading.explicit).map((heading) => heading.slug));
+	for (const heading of headings) {
+		if (heading.explicit) continue;
+		const base = heading.slug || "section";
+		let slug = base;
+		let suffix = 1;
+		while (used.has(slug)) {
+			suffix += 1;
+			slug = `${base}-${suffix}`;
+		}
+		heading.slug = slug;
+		used.add(slug);
+	}
+}
+/**
+* Finds the `id` of a wrapper element already anchoring this heading. Requiring
+* the heading to be its only child rules out containers like `<Tab>`.
 */
-function hasExplicitId(heading, _ast) {
-	const lastChild = heading.children[heading.children.length - 1];
-	if (lastChild?.type === "text") return /(\{#[^}]+\}|\\\{#[^}]+\\\}|\[[^\]]+\])\s*$/.test(lastChild.value);
-	return false;
+function findWrapperId(heading, parent) {
+	if (!parent || parent.type !== "mdxJsxFlowElement") return null;
+	const element = parent;
+	if (element.children.length !== 1 || element.children[0] !== heading) return null;
+	const position = element.attributes.find((attribute) => attribute.type === "mdxJsxAttribute" && attribute.name === "id")?.position;
+	if (!position || position.start.line !== position.end.line) return null;
+	return {
+		line: position.start.line,
+		startColumn: position.start.column,
+		endColumn: position.end.column
+	};
 }
 /**
-* Extracts heading information from content (read-only, no modifications)
+* Extracts heading information from content (read-only, no modifications).
+* Source and translation are matched by position, so both must parse the same
+* way — the fallback extractor misses headings nested in JSX.
 */
 function extractHeadingInfo(mdxContent) {
-	const headings = [];
-	let processedAst;
+	let ast;
 	try {
-		const parseProcessor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml", "toml"]).use(remarkMdx);
-		const ast = parseProcessor.parse(mdxContent);
-		processedAst = parseProcessor.runSync(ast);
+		ast = parseMdxTolerantly(mdxContent);
 	} catch {
 		return extractHeadingsWithFallback(mdxContent);
 	}
+	const headings = [];
 	let position = 0;
-	visit(processedAst, "heading", (heading) => {
+	visit(ast, "heading", (heading, _index, parent) => {
 		const { cleanedText, explicitId } = parseHeadingContent(extractHeadingText(heading));
-		if (cleanedText || explicitId) {
-			const slug = explicitId ?? generateSlug(cleanedText);
-			headings.push({
-				text: cleanedText,
-				level: heading.depth,
-				slug,
-				position: position++
-			});
-		}
+		if (!cleanedText && !explicitId) return;
+		const lastChild = heading.children[heading.children.length - 1];
+		headings.push({
+			text: cleanedText,
+			level: heading.depth,
+			slug: explicitId ?? generateSlug(cleanedText),
+			position: position++,
+			startLine: heading.position?.start.line ?? -1,
+			endLine: heading.position?.end.line ?? -1,
+			startColumn: heading.position?.start.column ?? 1,
+			textEndColumn: lastChild?.position?.end.column ?? heading.position?.end.column ?? -1,
+			wrapperId: findWrapperId(heading, parent),
+			explicit: explicitId !== void 0
+		});
 	});
+	assignUniqueSlugs(headings);
 	return headings;
 }
 /**
@@ -123,23 +144,28 @@ function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sou
 	sourceHeadingMap.forEach((sourceHeading, index) => {
 		const translatedHeading = translatedHeadings[index];
 		if (translatedHeading && translatedHeading.level === sourceHeading.level) {
-			idMappings.set(index, sourceHeading.slug);
+			idMappings.set(index, {
+				id: sourceHeading.slug,
+				explicit: sourceHeading.explicit
+			});
 			addedIds.push({
 				heading: translatedHeading.text,
 				id: sourceHeading.slug
 			});
 		}
 	});
-	if (idMappings.size === 0) return {
-		content: translatedContent,
-		hasChanges: false,
-		addedIds: []
-	};
 	const translatedIsMdx = translatedPath ? translatedPath.toLowerCase().endsWith(".mdx") : true;
 	const shouldEscapeAnchors = fileTypeHint === "mdx" ? true : fileTypeHint === "md" ? false : translatedIsMdx;
-	let content;
-	if (useDivWrapping) content = applyDivWrappedIds(translatedContent, translatedHeadings, idMappings);
-	else content = applyInlineIds(translatedContent, idMappings, shouldEscapeAnchors);
+	if (idMappings.size === 0) {
+		const content = useDivWrapping ? translatedContent : normalizeInlineAnchors(translatedContent, shouldEscapeAnchors);
+		return {
+			content,
+			hasChanges: content !== translatedContent,
+			addedIds: []
+		};
+	}
+	let content = applyAnchorIds(translatedContent, translatedHeadings, idMappings, useDivWrapping, shouldEscapeAnchors);
+	if (!useDivWrapping) content = normalizeInlineAnchors(content, shouldEscapeAnchors);
 	return {
 		content,
 		hasChanges: content !== translatedContent,
@@ -147,149 +173,55 @@ function addExplicitAnchorIds(translatedContent, sourceHeadingMap, settings, sou
 	};
 }
 /**
-* Adds inline {#id} syntax to headings (standard markdown approach)
+* Writes anchor IDs onto the translated document, locating headings by parser
+* line position rather than by text. Edits run bottom-up to keep lines valid.
 */
-function applyInlineIds(translatedContent, idMappings, escapeAnchors) {
-	const escapeInlineAnchors = (content) => {
-		if (!escapeAnchors) return content;
-		return content.replace(/\{#([A-Za-z0-9-_]+)\}/g, (match, id, offset, str) => {
-			if (offset > 0 && str[offset - 1] === "\\") return match;
-			return `\\{#${id}\\}`;
-		});
-	};
-	let processedAst;
-	try {
-		const parseProcessor = unified().use(remarkParse).use(remarkFrontmatter, ["yaml", "toml"]).use(remarkMdx);
-		const ast = parseProcessor.parse(translatedContent);
-		processedAst = parseProcessor.runSync(ast);
-	} catch {
-		return applyInlineIdsStringFallback(translatedContent, idMappings, escapeAnchors);
-	}
-	let headingIndex = 0;
-	let actuallyModifiedContent = false;
-	visit(processedAst, "heading", (heading) => {
-		const id = idMappings.get(headingIndex);
-		if (id) {
-			if (hasExplicitId(heading, processedAst)) {
-				if (escapeAnchors) {
-					const lastChild = heading.children[heading.children.length - 1];
-					if (lastChild?.type === "text") {
-						const match = lastChild.value.match(/\{#([^}]+)\}\s*$/);
-						const alreadyEscaped = lastChild.value.match(/\\\{#[^}]+\\\}\s*$/);
-						if (match && !alreadyEscaped) {
-							const anchorId = match[1];
-							lastChild.value = `${lastChild.value.replace(/\s*\{#[^}]+\}\s*$/, "")} \\{#${anchorId}\\}`;
-							actuallyModifiedContent = true;
-						}
-					}
-				}
-				headingIndex++;
-				return;
-			}
-			const lastChild = heading.children[heading.children.length - 1];
-			if (lastChild?.type === "text") lastChild.value += escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`;
-			else heading.children.push({
-				type: "text",
-				value: escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`
-			});
-			actuallyModifiedContent = true;
-		}
-		headingIndex++;
-	});
-	if (!actuallyModifiedContent) return escapeInlineAnchors(translatedContent);
-	try {
-		const stringifyProcessor = unified().use(remarkFrontmatter, ["yaml", "toml"]).use(remarkMdx).use(normalizeCJKCharacters).use(escapeHtmlInTextNodes).use(remarkStringify, { handlers: { text(node) {
-			return node.value;
-		} } });
-		const outTree = stringifyProcessor.runSync(processedAst);
-		let content = stringifyProcessor.stringify(outTree);
-		if (content.endsWith("\n") && !translatedContent.endsWith("\n")) content = content.slice(0, -1);
-		if (translatedContent.startsWith("\n") && !content.startsWith("\n")) content = "\n" + content;
-		return content;
-	} catch {
-		return translatedContent;
-	}
-}
-/**
-* Fallback string-based inline ID application when AST parsing fails
-*/
-function applyInlineIdsStringFallback(translatedContent, idMappings, escapeAnchors) {
-	let headingIndex = 0;
-	let inFence = false;
-	let fenceChar = null;
-	return translatedContent.split("\n").map((line) => {
-		const fenceMatch = line.match(/^(\s*)(`{3,}|~{3,})/);
-		if (fenceMatch) {
-			const fenceString = fenceMatch[2];
-			if (!inFence) {
-				inFence = true;
-				fenceChar = fenceString;
-			} else if (fenceChar && fenceString[0] === fenceChar[0] && fenceString.length >= fenceChar.length) {
-				inFence = false;
-				fenceChar = null;
-			}
-			return line;
+function applyAnchorIds(translatedContent, translatedHeadings, idMappings, useDivWrapping, escapeAnchors) {
+	const lines = translatedContent.split("\n");
+	const ordered = [...translatedHeadings].sort((a, b) => b.startLine - a.startLine);
+	for (const heading of ordered) {
+		const mapping = idMappings.get(heading.position);
+		if (!mapping) continue;
+		if (heading.startLine < 1 || heading.endLine > lines.length) continue;
+		const index = heading.startLine - 1;
+		if (!useDivWrapping || mapping.explicit) {
+			if (heading.textEndColumn < 1) continue;
+			const anchor = escapeAnchors && !mapping.explicit ? `\\{#${mapping.id}\\}` : `{#${mapping.id}}`;
+			const line = lines[index];
+			lines[index] = `${line.slice(0, heading.textEndColumn - 1).replace(TRAILING_ANCHOR, "")} ${anchor}${line.slice(heading.textEndColumn - 1)}`;
+			continue;
 		}
-		if (inFence) return line;
-		const headingMatch = line.match(/^(#{1,6}\s+)(.*)$/);
-		if (!headingMatch) return line;
-		const prefix = headingMatch[1];
-		const text = headingMatch[2];
-		const id = idMappings.get(headingIndex++);
-		if (!id) return line;
-		const hasEscaped = /\\\{#[^}]+\\\}\s*$/.test(text);
-		const hasUnescaped = /\{#[^}]+\}\s*$/.test(text);
-		if (hasEscaped) return line;
-		if (hasUnescaped) {
-			if (!escapeAnchors) return line;
-			return `${prefix}${text.replace(/\{#([^}]+)\}\s*$/, "\\{#$1\\}")}`;
+		if (heading.wrapperId) {
+			const { line, startColumn, endColumn } = heading.wrapperId;
+			const wrapper = lines[line - 1];
+			lines[line - 1] = wrapper.slice(0, startColumn - 1) + `id="${mapping.id}"` + wrapper.slice(endColumn - 1);
+			continue;
 		}
-		return `${prefix}${text}${escapeAnchors ? ` \\{#${id}\\}` : ` {#${id}}`}`;
-	}).join("\n");
+		const indent = lines[index].slice(0, Math.max(0, heading.startColumn - 1));
+		const body = lines.slice(index, heading.endLine).map((line) => `  ${line}`);
+		lines.splice(index, heading.endLine - heading.startLine + 1, `${indent}<div id="${mapping.id}">`, ...body, `${indent}</div>`);
+	}
+	return lines.join("\n");
 }
 /**
-* Wraps headings in divs with IDs (Mintlify approach)
+* Normalizes every inline anchor: escaped for MDX, bare for Markdown.
 */
-function applyDivWrappedIds(translatedContent, translatedHeadings, idMappings) {
-	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
-			});
+function normalizeInlineAnchors(content, escapeAnchors) {
+	return mapLinesOutsideCodeFences(content, (line) => {
+		const atx = line.match(ATX_HEADING);
+		if (!atx) return line;
+		const escaped = atx[3].match(/\\\{#([A-Za-z0-9_-]+)\\\}\s*$/);
+		const bare = atx[3].match(/(?<!\\)\{#([A-Za-z0-9_-]+)\}\s*$/);
+		if (escapeAnchors && bare) {
+			const text = atx[3].replace(TRAILING_ANCHOR, "");
+			return `${atx[1]}${atx[2]}${text} \\{#${bare[1]}\\}`;
 		}
-	});
-	let content = translatedContent;
-	const headingsToWrap = [];
-	translatedHeadings.forEach((heading, position) => {
-		const id = idMappings.get(position);
-		if (id) {
-			const matchingLine = headingLines.find((hl) => {
-				return decode(hl.line.replace(/^#{1,6}\s+/, "").trim().replace(/\*\*(.*?)\*\*/g, "$1").replace(/\*(.*?)\*/g, "$1").replace(/`(.*?)`/g, "$1").replace(/\[(.*?)\]\(.*?\)/g, "$1").trim()).trim() === decode(heading.text).trim() && hl.level === heading.level;
-			});
-			if (matchingLine) headingsToWrap.push({
-				originalLine: matchingLine.line,
-				id
-			});
+		if (!escapeAnchors && escaped) {
+			const text = atx[3].replace(TRAILING_ANCHOR, "");
+			return `${atx[1]}${atx[2]}${text} {#${escaped[1]}}`;
 		}
+		return line;
 	});
-	if (headingsToWrap.length > 0) {
-		const sortedHeadings = headingsToWrap.sort((a, b) => b.originalLine.length - a.originalLine.length);
-		for (const heading of sortedHeadings) {
-			if (content.includes(`<div id="${heading.id}">`)) continue;
-			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;
 }
 //#endregion
 export { addExplicitAnchorIds, extractHeadingInfo };