@mui/internal-docs-infra/pipeline/syncPageIndex/createMarkdownNodes.mjs

MUI Infra - internal documentation creation tools.

/**
 * createMarkdownNodes.ts - Helper functions for creating MD AST nodes
 *
 * This module provides utility functions to create nodes for Markdown
 * abstract syntax trees, making transformer code more readable and maintainable.
 */

/**
 * Create a text node
 * @param value - The text content
 * @returns A text node
 */
export function text(value) {
  return {
    type: 'text',
    value: value || ''
  };
}
/**
 * Helper to normalize children (handles string, node, or array)
 * @param children - Child content
 * @returns Normalized array of nodes
 */
function normalizeChildren(children) {
  // Handle empty or undefined
  if (!children) {
    return [];
  }

  // Convert to array if not already
  const childArray = Array.isArray(children) ? children : [children];

  // Convert strings to text nodes
  return childArray.map(child => typeof child === 'string' ? text(child) : child);
}

/**
 * Create a paragraph node
 * @param children - Child node, string, or array of nodes/strings
 * @returns A paragraph node
 */
export function paragraph(children) {
  return {
    type: 'paragraph',
    children: normalizeChildren(children)
  };
}

/**
 * Create an emphasis (italic) node
 * @param children - Child node, string, or array of nodes/strings
 * @returns An emphasis node
 */
export function emphasis(children) {
  return {
    type: 'emphasis',
    children: normalizeChildren(children)
  };
}

/**
 * Create a strong (bold) node
 * @param children - Child node, string, or array of nodes/strings
 * @returns A strong node
 */
export function strong(children) {
  return {
    type: 'strong',
    children: normalizeChildren(children)
  };
}

/**
 * Create a heading node
 * @param depth - Heading level (1-6)
 * @param children - Child node, string, or array of nodes/strings
 * @returns A heading node
 */
export function heading(depth, children) {
  return {
    type: 'heading',
    depth: depth || 1,
    children: normalizeChildren(children)
  };
}

/**
 * Create a code block node
 * @param {string} value - Code content
 * @param {string} lang - Language for syntax highlighting
 * @returns {Object} A code node
 */
export function code(value, lang) {
  return {
    type: 'code',
    lang: lang || null,
    value: value || ''
  };
}

/**
 * Create an inline code node
 * @param {string} value - Code content
 * @returns {Object} An inline code node
 */
export function inlineCode(value) {
  return {
    type: 'inlineCode',
    value: value || ''
  };
}

/**
 * Create a hard line break node (renders as <br> in HTML)
 * @returns A break node
 */
export function hardBreak() {
  return {
    type: 'break'
  };
}

/**
 * Creates a table cell node
 * @param content - Cell content
 * @returns Table cell node
 */
function tableCell(content) {
  return {
    type: 'tableCell',
    children: normalizeChildren(content)
  };
}

/**
 * Creates a table row node
 * @param cells - Array of cell contents
 * @returns Table row node
 */
function tableRow(cells) {
  return {
    type: 'tableRow',
    children: cells.map(cell => tableCell(cell))
  };
}

/**
 * Creates a markdown table node (GFM)
 * @param {Array<string|Object>} headers - Array of header strings or nodes
 * @param {Array<Array<string|Object>>} rows - Array of row data, each row is an array of cell content
 * @param {Array<string>} [alignment] - Optional array of alignments ('left', 'center', 'right') for each column
 * @returns {Object} A table node
 */
export function table(headers, rows, alignment = null) {
  // Convert alignment strings to AST format
  const align = headers.map((_, index) => {
    if (!alignment || !alignment[index]) {
      return null;
    }
    switch (alignment[index]) {
      case 'center':
        return 'center';
      case 'right':
        return 'right';
      default:
        return 'left';
    }
  });

  // Create header row
  const headerRow = tableRow(headers);

  // Create data rows - rows is actually an array of arrays
  const dataRows = rows.map(row => tableRow(row));

  // Return table node
  return {
    type: 'table',
    align,
    children: [headerRow, ...dataRows]
  };
}

/**
 * Create a list item node
 * @param children - Child node, string, or array of nodes/strings
 * @returns A list item node
 */
export function listItem(children) {
  return {
    type: 'listItem',
    spread: false,
    children: [paragraph(children)]
  };
}

/**
 * Create a list node
 * @param items - Array of list item nodes
 * @param ordered - Whether the list is ordered (numbered) or unordered (bulleted)
 * @returns A list node
 */
export function list(items, ordered = false) {
  return {
    type: 'list',
    ordered,
    spread: false,
    children: items
  };
}

/**
 * Create a comment node. Comment text will not be rendered in HTML output.
 * @param value - Comment text
 * @returns A comment node
 */
export function comment(value, ref) {
  return {
    type: 'definition',
    identifier: '//',
    url: ref || '#',
    title: value
  };
}

/**
 * Create a link node
 * @param url - The URL to link to
 * @param children - Child node, string, or array of nodes/strings
 * @param title - Optional title attribute
 * @returns A link node
 */
export function link(url, children, title) {
  return {
    type: 'link',
    url,
    title,
    children: normalizeChildren(children)
  };
}

/**
 * Create a raw HTML node. Content passes through without escaping.
 * Use sparingly - only when you need to prevent character escaping.
 * @param value - Raw HTML/text content
 * @returns An HTML node
 */
export function raw(value) {
  return {
    type: 'html',
    value
  };
}