Typescript: Support generating MDX files

Author: fuma-nama

.changeset/sixty-cooks-kneel.md

@@ -0,0 +1,5 @@
+---
+'fumadocs-typescript': minor
+---
+
+Support generating MDX files

packages/typescript/src/generate.ts

@@ -0,0 +1,120 @@
+import * as ts from 'typescript';
+import { type TypescriptConfig, getProgram } from './program';
+
+export interface GeneratedDoc {
+  name: string;
+  description: string;
+  entries: DocEntry[];
+}
+
+export interface DocEntry {
+  name: string;
+  description: string;
+  type: string;
+  tags: Record<string, string>;
+}
+
+interface EntryContext {
+  program: ts.Program;
+  checker: ts.TypeChecker;
+  options: GenerateOptions;
+  type: ts.Type;
+  symbol: ts.Symbol;
+}
+
+export interface GenerateOptions {
+  file: string;
+  name: string;
+  /**
+   * Modify output property entry
+   */
+  transform?: (
+    this: EntryContext,
+    entry: DocEntry,
+    propertyType: ts.Type,
+    propertySymbol: ts.Symbol,
+  ) => void;
+
+  /**
+   * Typescript configurations
+   */
+  options?: TypescriptConfig;
+}
+
+/**
+ * Generate documentation for properties in an exported type/interface
+ */
+export function generateDocumentation(
+  options: GenerateOptions,
+): GeneratedDoc | undefined {
+  const program = getProgram(options.options);
+  return generateDocumentationFromProgram(program, options);
+}
+
+export function generateDocumentationFromProgram(
+  program: ts.Program,
+  options: GenerateOptions,
+): GeneratedDoc | undefined {
+  const checker = program.getTypeChecker();
+  const sourceFile = program.getSourceFile(options.file);
+  if (!sourceFile) return;
+
+  const fileSymbol = checker.getSymbolAtLocation(sourceFile);
+  if (!fileSymbol) return;
+
+  const symbol = checker
+    .getExportsOfModule(fileSymbol)
+    .find((e) => e.getEscapedName().toString() === options.name);
+
+  if (!symbol) return;
+
+  const type = checker.getDeclaredTypeOfSymbol(symbol);
+
+  const entryContext: EntryContext = {
+    checker,
+    options,
+    program,
+    type,
+    symbol,
+  };
+
+  return {
+    name: symbol.getEscapedName().toString(),
+    description: ts.displayPartsToString(
+      symbol.getDocumentationComment(checker),
+    ),
+    entries: type
+      .getProperties()
+      .map((prop) => getDocEntry(prop, entryContext)),
+  };
+}
+
+function getDocEntry(prop: ts.Symbol, context: EntryContext): DocEntry {
+  const { checker, options } = context;
+  const subType = checker.getTypeOfSymbol(prop);
+
+  let typeName = checker.typeToString(
+    subType.getNonNullableType(),
+    undefined,
+    ts.TypeFormatFlags.UseAliasDefinedOutsideCurrentScope,
+  );
+
+  if (subType.aliasSymbol && !subType.aliasTypeArguments) {
+    typeName = subType.aliasSymbol.escapedName.toString();
+  }
+
+  const entry: DocEntry = {
+    name: prop.getName(),
+    description: ts.displayPartsToString(prop.getDocumentationComment(checker)),
+    tags: Object.fromEntries(
+      prop
+        .getJsDocTags()
+        .map((tag) => [tag.name, ts.displayPartsToString(tag.text)]),
+    ),
+    type: typeName,
+  };
+
+  options.transform?.call(context, entry, subType, prop);
+
+  return entry;
+}

packages/typescript/src/generate/base.ts

@@ -0,0 +1,79 @@
+import * as path from 'node:path';
+import {
+  type DocEntry,
+  type GeneratedDoc,
+  generateDocumentationFromProgram,
+} from './base';
+import { type TypescriptConfig, getProgram } from './program';
+
+interface Templates {
+  block: (doc: GeneratedDoc, children: string) => string;
+  property: (entry: DocEntry) => string;
+}
+
+export interface GenerateMDXOptions {
+  /**
+   * a root directory to resolve relative file paths
+   */
+  basePath?: string;
+  templates?: Partial<Templates>;
+  options?: TypescriptConfig;
+}
+
+// \r?\n is required for cross-platform compatibility
+const regex =
+  /^---type-table---\r?\n(?<file>.+?)(?:#(?<name>.+))?\r?\n---end---$/gm;
+
+const defaultTemplates: Templates = {
+  block: (doc, c) => `### ${doc.name}
+
+${doc.description}
+
+<div className='flex flex-col gap-4 *:border-b [&>*:last-child]:border-b-0'>${c}</div>`,
+
+  property: (c) => `<div className='text-sm text-muted-foreground'>
+
+<div className="flex flex-row items-center gap-4">
+  <code className="text-sm">${c.name}</code>
+  <code className="text-muted-foreground">${c.type}</code>
+</div>
+
+${c.description || 'No Description'}
+
+${Object.entries(c.tags)
+  .map(([tag, value]) => `**${tag}:** ${replaceJsDocLinks(value)}`)
+  .join('<br/>\n')}
+
+</div>`,
+};
+
+export function generateMDX(
+  source: string,
+  { basePath = './', templates: overrides, options }: GenerateMDXOptions = {},
+): string {
+  const templates = { ...defaultTemplates, ...overrides };
+  const program = getProgram(options);
+
+  return source.replace(regex, (v, ...args) => {
+    const groups = args[args.length - 1] as Record<string, string>;
+
+    if (!groups.file || !groups.name) return v;
+
+    const result = generateDocumentationFromProgram(program, {
+      file: path.resolve(basePath, groups.file),
+      name: groups.name,
+      options,
+    });
+
+    if (!result) throw new Error(`Exported type ${groups.name} doesn't exist`);
+
+    return templates.block(
+      result,
+      result.entries.map(templates.property).join('\n'),
+    );
+  });
+}
+
+function replaceJsDocLinks(md: string): string {
+  return md.replace(/{@link (?<link>[^}]*)}/g, '$1');
+}

packages/typescript/src/generate/mdx.ts

@@ -0,0 +1,40 @@
+import * as ts from 'typescript';
+
+const cache = new Map<string, ts.Program>();
+
+export interface TypescriptConfig {
+  files?: string[];
+  tsconfigPath?: string;
+  /** A root directory to resolve relative path entries in the config file to. e.g. outDir */
+  basePath?: string;
+}
+
+export function getProgram(options: TypescriptConfig = {}): ts.Program {
+  const key = JSON.stringify(options);
+  const cached = cache.get(key);
+
+  if (cached) return cached;
+
+  const configFile = ts.readJsonConfigFile(
+    options.tsconfigPath ?? './tsconfig.json',
+    (path) => ts.sys.readFile(path),
+  );
+
+  const parsed = ts.parseJsonSourceFileConfigFileContent(
+    configFile,
+    ts.sys,
+    options.basePath ?? './',
+  );
+
+  const program = ts.createProgram({
+    rootNames: options.files ?? parsed.fileNames,
+    options: {
+      ...parsed.options,
+      incremental: false,
+    },
+  });
+
+  cache.set(key, program);
+
+  return program;
+}

packages/typescript/src/generate/program.ts

@@ -1 +1,2 @@
-export * from './generate';
+export * from './generate/base';
+export * from './generate/mdx';