@diplodoc/transform 4.73.2 → 4.74.0

package/src/transform/md.ts

@@ -13,6 +13,7 @@ import getHeadings from './headings';
 import sanitizeHtml, {defaultOptions, sanitizeStyles} from './sanitize';
 import {olAttrConversion} from './plugins/ol-attr-conversion';
 import {DEFAULT_LANG} from './constants';
+import {createIDGeneratorByStrategy} from './plugins/utils';
 
 function initMarkdownIt(options: OptionsType) {
     const {
@@ -80,6 +81,7 @@ function getPluginOptions(options: OptionsType) {
             enabled: true,
             maxFileSize: 2 * 1024 * 1024,
         },
+        generateID,
         ...customOptions
     } = options;
 
@@ -93,6 +95,7 @@ function getPluginOptions(options: OptionsType) {
         log,
         lang,
         svgInline,
+        generateID: generateID ?? createIDGeneratorByStrategy('random'),
     } as MarkdownItPluginOpts;
 }
 

package/src/transform/plugins/anchors/index.ts

@@ -111,7 +111,10 @@ const index: MarkdownItPluginCb<Options> = (md, options) => {
                 }
 
                 if (level < 2 && extractTitle) {
-                    // if there are any custom ids in the level 1 heading we should clear them
+                    const customIds = getCustomIds(inlineToken.content);
+                    if (customIds) {
+                        token.attrSet('id', customIds[0]);
+                    }
                     removeCustomIds(tokens[i + 1]);
                     i += 3;
                     continue;

package/src/transform/plugins/code.ts

@@ -1,8 +1,9 @@
 /* eslint-disable max-len */
 
 import type {MarkdownItPluginCb} from './typings';
+import type {IDGenerator} from './utils';
 
-import {generateID} from './utils';
+import {generateID as globalGenerateID} from './utils';
 
 const wrapInFloatingContainer = (
     element: string | undefined,
@@ -72,7 +73,12 @@ interface EnvTerm {
     };
 }
 
-function termReplace(str: string, env: EnvTerm, escape: (str: string) => string): string {
+function termReplace(
+    str: string,
+    env: EnvTerm,
+    escape: (str: string) => string,
+    generateID: IDGenerator,
+): string {
     const regTerms = Object.keys(env.terms)
         .map((el) => el.slice(1))
         .map(escape)
@@ -83,7 +89,7 @@ function termReplace(str: string, env: EnvTerm, escape: (str: string) => string)
     const termCode = str.replace(
         reg,
         (_match: string, p1: string, _p2: string, p3: string) =>
-            `<i class="yfm yfm-term_title" term-key=":${p3}" id="${generateID()}">${p1}</i>`,
+            `<i class="yfm yfm-term_title" term-key=":${p3}" id="${generateID(p3)}">${p1}</i>`,
     );
 
     return termCode || str;
@@ -100,6 +106,8 @@ const SPAN_TAG_RE = /<span[^>]*>|<\/span>/g;
  *   `['<span class="hljs-string">\'line1', 'line2\'</span>']`
  * After:
  *   `['<span class="hljs-string">\'line1</span>', '<span class="hljs-string">line2\'</span>']`
+ * @param lines - Highlighted HTML split into separate lines.
+ * @returns Lines with balanced `<span>` tags on each line.
  */
 function balanceSpansPerLine(lines: string[]): string[] {
     const openTagStack: string[] = [];
@@ -152,6 +160,7 @@ type CodeOptions = {
 
 const code: MarkdownItPluginCb<CodeOptions> = (md, opts) => {
     const lineWrapping = opts?.codeLineWrapping || false;
+    const generateID = opts.generateID ?? globalGenerateID;
 
     const superCodeRenderer = md.renderer.rules.fence;
     md.renderer.rules.fence = function (tokens, idx, options, env, self) {
@@ -173,7 +182,9 @@ const code: MarkdownItPluginCb<CodeOptions> = (md, opts) => {
         }
 
         const superCodeWithTerms =
-            superCode && env?.terms ? termReplace(superCode, env, md.utils.escapeRE) : superCode;
+            superCode && env?.terms
+                ? termReplace(superCode, env, md.utils.escapeRE, generateID)
+                : superCode;
 
         return wrapInFloatingContainer(superCodeWithTerms, idx, {lineWrapping});
     };

package/src/transform/plugins/images/index.ts

@@ -1,6 +1,7 @@
 import type Token from 'markdown-it/lib/token';
 import type {MarkdownItPluginCb, MarkdownItPluginOpts} from '../typings';
 import type {ImageOptions, StateCore} from '../../typings';
+import type {IDGenerator} from '../utils';
 
 import {join, sep} from 'path';
 import {bold} from 'chalk';
@@ -9,6 +10,7 @@ import {readFileSync} from 'fs';
 
 import {isFileExists, resolveRelativePath} from '../../utilsFS';
 import {filterTokens, getSrcTokenAttr, isExternalHref} from '../../utils';
+import {generateID as globalGenerateID} from '../utils';
 
 const sanitizeAttribute = (value: string): string => value.replace(/(\d*[%a-z]{0,5}).*/gi, '$1');
 
@@ -166,7 +168,10 @@ const index: MarkdownItPluginCb<Opts> = (md, opts) => {
                             );
                         } else {
                             const svgToken = new state.Token('image_svg', '', 0);
-                            svgToken.attrSet('content', replaceSvgContent(svgContent, imageOpts));
+                            svgToken.attrSet(
+                                'content',
+                                replaceSvgContent(svgContent, imageOpts, opts.generateID),
+                            );
                             childrenTokens[index] = svgToken;
                         }
                     }
@@ -193,7 +198,11 @@ const index: MarkdownItPluginCb<Opts> = (md, opts) => {
     };
 };
 
-function replaceSvgContent(content: string | null, options: ImageOptions) {
+function replaceSvgContent(
+    content: string | null,
+    options: ImageOptions,
+    generateID: IDGenerator = globalGenerateID,
+) {
     if (!content) {
         return '';
     }
@@ -239,7 +248,7 @@ function replaceSvgContent(content: string | null, options: ImageOptions) {
             {
                 name: 'prefixIds',
                 params: {
-                    prefix: 'rnd-' + Math.floor(Math.random() * 1e9).toString(16),
+                    prefix: generateID('svg'),
                     prefixClassNames: false,
                 },
             },

package/src/transform/plugins/inline-code/index.ts

@@ -2,20 +2,21 @@ import type {MarkdownItPluginCb} from '../../typings';
 
 import {escapeHtml} from 'markdown-it/lib/common/utils';
 
-import {generateID} from '../utils';
+import {generateID as globalGenerateID} from '../utils';
 
 import {LANG_TOKEN_DESCRIPTION, LANG_TOKEN_LABEL} from './constant';
 
 const inlineCode: MarkdownItPluginCb = (md, options) => {
     const lang = options.lang;
+    const generateID = options.generateID ?? globalGenerateID;
 
     md.renderer.rules.code_inline = function (tokens, idx) {
-        const id = generateID();
+        const id = generateID('inline-code-id');
 
         const description = LANG_TOKEN_DESCRIPTION[lang] ?? LANG_TOKEN_DESCRIPTION.en;
         const label = LANG_TOKEN_LABEL[lang] ?? LANG_TOKEN_LABEL.en;
 
-        return `<code class="yfm-clipboard-inline-code" role="button" aria-label="${label}" aria-description="${description}" tabindex='0' id="inline-code-id-${id}">${escapeHtml(tokens[idx].content)}</code>`;
+        return `<code class="yfm-clipboard-inline-code" role="button" aria-label="${label}" aria-description="${description}" tabindex='0' id="${id}">${escapeHtml(tokens[idx].content)}</code>`;
     };
 };
 

package/src/transform/plugins/term/index.ts

@@ -2,19 +2,20 @@ import type StateCore from 'markdown-it/lib/rules_core/state_core';
 import type StateInline from 'markdown-it/lib/rules_inline/state_inline';
 import type Token from 'markdown-it/lib/token';
 import type {MarkdownItPluginCb} from '../typings';
+import type {IDGenerator} from '../utils';
 
-import {generateID} from '../utils';
+import {generateID as globalGenerateID} from '../utils';
 
 import {termDefinitions} from './termDefinitions';
 import {BASIC_TERM_REGEXP} from './constants';
 
-function setTermAttrs(token: Token, termKey: string): void {
+function setTermAttrs(token: Token, termKey: string, generateID: IDGenerator): void {
     token.attrSet('class', 'yfm yfm-term_title');
     token.attrSet('term-key', ':' + termKey);
     token.attrSet('role', 'button');
     token.attrSet('aria-controls', ':' + termKey + '_element');
     token.attrSet('tabindex', '0');
-    token.attrSet('id', generateID());
+    token.attrSet('id', generateID(termKey));
 }
 
 interface TermMatch {
@@ -88,38 +89,41 @@ function matchTermPattern(src: string, start: number, max: number): TermMatch |
 }
 
 /**
- * Inline rule that matches [text](*termId) for defined terms.
+ * Creates an inline rule that matches [text](*termId) for defined terms.
  * Runs before the link rule so that * characters inside the
  * pattern are consumed and never trigger emphasis.
  *
- * @param state - inline parser state
- * @param silent - if true, only validate without creating tokens
- * @returns true if the pattern was matched
+ * @param generateID - per-file isolated ID generator
+ * @returns inline rule function for markdown-it
  */
-function termInlineRule(state: StateInline, silent: boolean): boolean {
-    if (state.src.charCodeAt(state.pos) !== 0x5b /* [ */ || !state.env.terms) {
-        return false;
-    }
+function termInlineRuleFactory(generateID: IDGenerator) {
+    return function termInlineRule(state: StateInline, silent: boolean): boolean {
+        if (state.src.charCodeAt(state.pos) !== 0x5b /* [ */ || !state.env.terms) {
+            return false;
+        }
 
-    const match = matchTermPattern(state.src, state.pos, state.posMax);
-    if (!match || !state.env.terms[':' + match.termId]) {
-        return false;
-    }
+        const match = matchTermPattern(state.src, state.pos, state.posMax);
+        if (!match || !state.env.terms[':' + match.termId]) {
+            return false;
+        }
 
-    if (!silent) {
-        const labelContent = state.src.slice(state.pos + 1, match.labelEnd).replace(/\\(.)/g, '$1');
+        if (!silent) {
+            const labelContent = state.src
+                .slice(state.pos + 1, match.labelEnd)
+                .replace(/\\(.)/g, '$1');
 
-        const termOpen = state.push('term_open', 'i', 1);
-        setTermAttrs(termOpen, match.termId);
+            const termOpen = state.push('term_open', 'i', 1);
+            setTermAttrs(termOpen, match.termId, generateID);
 
-        const textToken = state.push('text', '', 0);
-        textToken.content = labelContent;
+            const textToken = state.push('text', '', 0);
+            textToken.content = labelContent;
 
-        state.push('term_close', 'i', -1);
-    }
+            state.push('term_close', 'i', -1);
+        }
 
-    state.pos = match.endPos;
-    return true;
+        state.pos = match.endPos;
+        return true;
+    };
 }
 
 const RAW_CODE_TOKEN_TYPES = new Set(['fence', 'code_block', 'yfm_page-constructor']);
@@ -139,10 +143,21 @@ function collectTermsFromRawContent(tokens: Token[], reg: RegExp, out: Set<strin
             collectRawTermMatches(token.content, reg, out);
         }
 
-        if (token.type === 'inline' && token.children) {
-            for (const child of token.children) {
-                if (child.type === 'code_inline' && child.content) {
-                    collectRawTermMatches(child.content, reg, out);
+        if (token.type === 'inline') {
+            // Scan the raw inline content to catch term references that
+            // may have been split across child tokens by emphasis parsing.
+            // When term definitions come from includes resolved after inline
+            // parsing, term_inline fails and `(*key)` gets fragmented by
+            // the `*` emphasis delimiter — making per-child scanning miss them.
+            if (token.content) {
+                collectRawTermMatches(token.content, reg, out);
+            }
+
+            if (token.children) {
+                for (const child of token.children) {
+                    if (child.type === 'code_inline' && child.content) {
+                        collectRawTermMatches(child.content, reg, out);
+                    }
                 }
             }
         }
@@ -241,6 +256,7 @@ const term: MarkdownItPluginCb = (md, options) => {
     const arrayReplaceAt = md.utils.arrayReplaceAt;
 
     const {isLintRun} = options;
+    const generateID = options.generateID ?? globalGenerateID;
 
     // Prevent * URLs from being parsed as regular links (backward compatibility)
     const defaultLinkValidation = md.validateLink;
@@ -253,7 +269,7 @@ const term: MarkdownItPluginCb = (md, options) => {
     };
 
     // Inline rule: handles [text](*termId) before emphasis can interfere with *
-    md.inline.ruler.before('link', 'term_inline', termInlineRule);
+    md.inline.ruler.before('link', 'term_inline', termInlineRuleFactory(generateID));
 
     function termReplace(state: StateCore) {
         let i, j, l, tokens, token, text, nodes, pos, termMatch, currentToken;
@@ -347,7 +363,7 @@ const term: MarkdownItPluginCb = (md, options) => {
                     }
 
                     token = new state.Token('term_open', 'i', 1);
-                    setTermAttrs(token, termKey);
+                    setTermAttrs(token, termKey, generateID);
                     nodes.push(token);
 
                     token = new state.Token('text', '', 0);
@@ -386,7 +402,15 @@ const term: MarkdownItPluginCb = (md, options) => {
         alt: ['paragraph', 'reference'],
     });
 
-    md.core.ruler.after('linkify', 'termReplace', termReplace);
+    // Register termReplace after text_join so that emphasis-split text
+    // tokens (e.g. [text](*key) where * opens a delimiter) are merged
+    // before the term regex runs.  Without this, terms defined in
+    // included files (resolved after inline parsing) would be missed.
+    try {
+        md.core.ruler.after('text_join', 'termReplace', termReplace);
+    } catch {
+        md.core.ruler.after('linkify', 'termReplace', termReplace);
+    }
 };
 
 export = term;

package/src/transform/plugins/utils.ts

@@ -3,6 +3,8 @@ import type {Logger} from '../log';
 
 import {bold} from 'chalk';
 import {platform} from 'process';
+export type {IDGenerator, IDGeneratorStrategy} from '@diplodoc/utils';
+export {createIDGenerator, createIDGeneratorByStrategy} from '@diplodoc/utils';
 
 export type MatchTokenFunction = (
     tokens: Token[],
@@ -34,8 +36,19 @@ export const nestedCloseTokenIdxFactory =
 
 export const сarriage = platform === 'win32' ? '\r\n' : '\n';
 
-export function generateID() {
-    return Math.random().toString(36).substr(2, 8);
+/**
+ * Generates a legacy random ID.
+ * @deprecated Use `options.generateID` from plugin context instead.
+ * Fallback preserves legacy random behavior without shared counter state.
+ * @param prefix - Optional prefix to prepend to the generated ID.
+ * @returns Random ID string, optionally prefixed with `${prefix}-`.
+ */
+export function generateID(prefix?: string): string {
+    if (!prefix) {
+        return Math.random().toString(36).substr(2, 8);
+    }
+
+    return `${prefix}-${Math.random().toString(36).substr(2, 8)}`;
 }
 
 export function append<T extends Record<string, []>, Key extends keyof T>(

package/src/transform/typings.ts

@@ -5,6 +5,7 @@ import type DefaultStateCore from 'markdown-it/lib/rules_core/state_core';
 import type {SanitizeFunction, SanitizeOptions} from './sanitize';
 import type {LogLevels, Logger} from './log';
 import type {ChangelogItem} from './plugins/changelog/types';
+import type {IDGenerator} from './plugins/utils';
 
 export interface MarkdownIt extends DefaultMarkdownIt {
     assets?: string[];
@@ -109,6 +110,15 @@ export interface OptionsType {
      * @default false
      */
     codeLineWrapping?: boolean;
+    /**
+     * Custom ID generator factory to use for this transform call.
+     * If provided, it will be called once per file to create a per-file isolated generator.
+     * If not provided, a new {@link IDGenerator} is created via {@link createIDGenerator}
+     * (deterministic per-file counters).
+     *
+     * Pass `() => () => Math.random().toString(36).substr(2, 8)` to restore legacy random behavior.
+     */
+    generateID?: IDGenerator;
 }
 
 export interface OutputType {
@@ -134,6 +144,7 @@ export interface MarkdownItPluginOpts {
     root: string;
     rootPublicPath: string;
     isLintRun: boolean;
+    generateID?: IDGenerator;
     cache?: CacheContext;
     conditionsInCode?: boolean;
     vars?: Record<string, string>;

package/src/transform/utils.ts

@@ -57,7 +57,7 @@ export function headingInfo(tokens: Token[], idx: number) {
     while (inlineToken.children && i < inlineToken.children.length) {
         const token = inlineToken.children[i];
 
-        if (token.type === 'text') {
+        if (token.type === 'text' || token.type === 'text_special') {
             title += token.content;
         }