Support links with custom '// @link' syntax

Author: ricardonunez-io

.yarn/install-state.gz

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/mdx",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Markdown parser from Mintlify",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

packages/mdx/package.json

@@ -1,15 +1,8 @@
-import {
-  createTransformerFactory,
-  rendererRich,
-  transformerTwoslash,
-  type TransformerTwoslashOptions,
-} from '@shikijs/twoslash';
+import { transformerTwoslash } from '@shikijs/twoslash';
 import type { Element, Root } from 'hast';
 import { toString } from 'hast-util-to-string';
 import type { MdxJsxFlowElementHast, MdxJsxTextElementHast } from 'mdast-util-mdx-jsx';
 import { createHighlighter, type Highlighter } from 'shiki';
-import { createTwoslashFromCDN } from 'twoslash-cdn';
-import ts from 'typescript';
 import type { Plugin } from 'unified';
 import { visit } from 'unist-util-visit';
 
@@ -27,30 +20,14 @@ import {
   DEFAULT_LANGS,
   SHIKI_TRANSFORMERS,
 } from './shiki-constants.js';
+import {
+  cdnTransformerTwoslash,
+  cdnTwoslash,
+  getTwoslashOptions,
+  parseLineComment,
+} from './twoslash/config.js';
 import { getLanguage } from './utils.js';
 
-const twoslashCompilerOptions = {
-  target: ts.ScriptTarget.ESNext,
-  lib: ['ESNext', 'DOM', 'esnext', 'dom', 'es2020'],
-};
-
-const twoslashOptions: TransformerTwoslashOptions = {
-  onTwoslashError(err, code, lang) {
-    console.error(JSON.stringify({ err, code, lang }));
-  },
-  onShikiError(err, code, lang) {
-    console.error(JSON.stringify({ err, code, lang }));
-  },
-  renderer: rendererRich(),
-  langs: ['ts', 'typescript', 'js', 'javascript', 'tsx', 'jsx'],
-  explicitTrigger: /mint-twoslash/,
-  twoslashOptions: { compilerOptions: twoslashCompilerOptions },
-};
-
-const cdnTwoslash = createTwoslashFromCDN({ compilerOptions: twoslashCompilerOptions });
-
-const cdnTransformerTwoslash = createTransformerFactory(cdnTwoslash.runSync);
-
 export type RehypeSyntaxHighlightingOptions = {
   theme?: ShikiTheme;
   themes?: Record<'light' | 'dark', ShikiTheme>;
@@ -145,7 +122,7 @@ const traverseNode = (
   options: RehypeSyntaxHighlightingOptions
 ) => {
   try {
-    const code = toString(node);
+    let code = toString(node);
 
     const meta = node.data?.meta?.split(' ') ?? [];
     const twoslashIndex = meta.findIndex((str) => str.toLowerCase() === 'mint-twoslash');
@@ -156,6 +133,20 @@ const traverseNode = (
       node.data.meta = meta.join(' ').trim() || undefined;
     }
 
+    const linkMap: Map<string, string> = new Map();
+    const splitCode = code.split('\n');
+    for (const [i, line] of splitCode.entries()) {
+      const parsedLineComment = parseLineComment(line);
+      if (!parsedLineComment) continue;
+      const { word, href } = parsedLineComment;
+      linkMap.set(word, href);
+      splitCode.splice(i, 1);
+    }
+
+    code = splitCode.join('\n');
+
+    const twoslashOptions = getTwoslashOptions({ linkMap });
+
     const hast = highlighter.codeToHast(code, {
       lang: lang ?? DEFAULT_LANG,
       meta: shouldUseTwoslash ? { __raw: 'mint-twoslash' } : undefined,

packages/mdx/src/plugins/rehype/rehypeSyntaxHighlighting.ts

@@ -0,0 +1,110 @@
+import {
+  createTransformerFactory,
+  rendererRich,
+  type TransformerTwoslashOptions,
+} from '@shikijs/twoslash';
+import type { ElementContent } from 'hast';
+import type { ShikiTransformer } from 'shiki/types';
+import { createTwoslashFromCDN, type TwoslashCdnReturn } from 'twoslash-cdn';
+import ts from 'typescript';
+
+type TransformerFactory = (options?: TransformerTwoslashOptions) => ShikiTransformer;
+
+const twoslashCompilerOptions: ts.CompilerOptions = {
+  target: ts.ScriptTarget.ESNext,
+  lib: ['ESNext', 'DOM', 'esnext', 'dom', 'es2020'],
+};
+
+export const cdnTwoslash: TwoslashCdnReturn = createTwoslashFromCDN({
+  compilerOptions: twoslashCompilerOptions,
+});
+export const cdnTransformerTwoslash: TransformerFactory = createTransformerFactory(
+  cdnTwoslash.runSync
+);
+
+function onTwoslashError(err: unknown, code: string, lang: string) {
+  console.error(JSON.stringify({ err, code, lang }));
+}
+
+function onShikiError(err: unknown, code: string, lang: string) {
+  console.error(JSON.stringify({ err, code, lang }));
+}
+
+export function getTwoslashOptions(
+  { linkMap }: { linkMap: Map<string, string> } = { linkMap: new Map() }
+): TransformerTwoslashOptions {
+  return {
+    onTwoslashError,
+    onShikiError,
+    renderer: rendererRich({
+      hast: {
+        hoverToken: {
+          children(input) {
+            for (const rootElement of input) {
+              if (!('children' in rootElement)) continue;
+              for (const [i, element] of rootElement.children.entries()) {
+                if (element.type !== 'text') continue;
+                const href = linkMap.get(element.value);
+                if (!href) continue;
+                const newElement: ElementContent = {
+                  type: 'element',
+                  tagName: 'a',
+                  properties: {
+                    href,
+                    ...(checkIsExternalLink(href) && {
+                      target: '_blank',
+                      rel: 'noopener noreferrer',
+                    }),
+                  },
+                  children: [{ type: 'text', value: element.value }],
+                };
+                input.splice(i, 1, newElement);
+              }
+            }
+            return input;
+          },
+        },
+      },
+    }),
+    langs: ['ts', 'typescript', 'js', 'javascript', 'tsx', 'jsx'],
+    explicitTrigger: /mint-twoslash/,
+    twoslashOptions: {
+      compilerOptions: twoslashCompilerOptions,
+    },
+  };
+}
+
+export function parseLineComment(line: string): { word: string; href: string } | undefined {
+  line = line.trim();
+  if (!line.startsWith('//') || (!line.includes('@link ') && !line.includes('@link:'))) return;
+
+  line = line.replace('@link:', '@link ');
+  const parts = line.split('@link ')[1];
+  if (!parts) return;
+
+  const words = parts.split(' ').filter(Boolean);
+  if (words.length === 1 && words[0]) {
+    let word = words[0];
+    if (word.endsWith(':')) word = word.slice(0, -1);
+    const lowercaseWord = word.toLowerCase();
+    const href = word.startsWith('#') ? lowercaseWord : `#${encodeURIComponent(lowercaseWord)}`;
+    return { word, href };
+  } else if (words.length === 2 && words[0] && words[1]) {
+    let word = words[0];
+    if (word.endsWith(':')) word = word.slice(0, -1);
+    const href = words[1];
+    if (!href.startsWith('#') && !href.startsWith('https://')) return;
+    return { word, href };
+  }
+
+  return;
+}
+
+type Url = `https://${string}`;
+function checkIsExternalLink(href: string | undefined): href is Url {
+  let isExternalLink = false;
+  try {
+    if (href && URL.canParse(href)) isExternalLink = true;
+  } catch {}
+  return isExternalLink;
+}