Micro MDX Parser

Common errors

• TypeError: (0 , micro_mdx_parser__WEBPACK_IMPORTED_MODULE_0__.parse) is not a function

  cause Incorrectly attempting to use a default import for `parse` in an environment where it's only exported as a named export.
  fix Change the import statement to use named import syntax: `import { parse } from 'micro-mdx-parser';`

• Error: Cannot find module 'micro-mdx-parser'

  cause The package has not been installed or is not resolvable in the current environment.
  fix Ensure the package is installed via `npm install micro-mdx-parser` or `yarn add micro-mdx-parser`, and that your module resolution paths are correctly configured.

• Property 'content' does not exist on type 'Element' or 'Root' or 'Node'.

  cause Attempting to access `content` directly on an element node (e.g., `h1`, `p`), which typically contains children nodes, not raw text content directly on the element itself. Text content is usually within child 'text' nodes.
  fix Access text content through child nodes of type 'text'. For example, `element.children[0].content` if the first child is a text node, or iterate through children to find text nodes.

Warnings

• gotcha The package is 'MDX-like', meaning it processes some MDX-specific syntax like components (e.g., `<MyComponent />`), but it is not a full MDX compiler. It does not evaluate JavaScript expressions within Markdown or handle complex MDX features like imports or JSX in Markdown beyond basic component tags. Developers expecting a full MDX runtime will find it lacking.
  Fix: For full MDX compilation with JavaScript evaluation, consider `MDX` (official package) or other robust MDX solutions. Use `micro-mdx-parser` when only a structural JSON representation of Markdown/HTML (including basic component tags) is needed.
• gotcha Being a fork of `himalaya`, `micro-mdx-parser` might exhibit subtle differences in parsing HTML compared to the original `himalaya` library, especially around edge cases or malformed HTML. While the core parsing logic is similar, the 'MDX-like' tweaks could introduce divergences.
  Fix: Thoroughly test parsing results with diverse HTML/Markdown inputs if migrating from `himalaya` or relying on specific parsing behaviors. Consult the source code if unexpected parsing results occur.
• gotcha The parser is designed to be 'tiny' and lightweight, which might mean it does not include extensive error handling or recovery mechanisms for highly malformed input. Invalid or unexpected syntax might lead to truncated output or unhandled errors rather than detailed diagnostics.
  Fix: Ensure input Markdown/HTML is as well-formed as possible. Implement input validation or pre-processing steps before feeding content to the parser, especially for user-generated content.
• gotcha While the package supports both browser and server environments, browser-specific build tooling or polyfills might be required for older browser targets, as the underlying `himalaya` library might use modern JavaScript features.
  Fix: Verify compatibility with target browser environments using modern bundlers (e.g., Webpack, Rollup, Vite) which can transpile or polyfill as needed. Test thoroughly in target browsers.

Install

• npm install micro-mdx-parser npm
• yarn add micro-mdx-parser yarn
• pnpm add micro-mdx-parser pnpm

Imports

• parse
  wrong:

  import parse from 'micro-mdx-parser';

  correct:

  import { parse } from 'micro-mdx-parser';

  The primary parsing function is a named export. While some tools might try a default import, it will likely fail.
• parse
  wrong:

  const parse = require('micro-mdx-parser').parse;

  correct:

  const { parse } = require('micro-mdx-parser');

  CommonJS environments should use destructuring for the named 'parse' export to maintain consistency with ESM.
• ParserOutput

  import type { ParserOutput } from 'micro-mdx-parser';

  For TypeScript users, import the type definition for the JSON output structure.

Quickstart

Demonstrates how to import the `parse` function and use it to convert both Markdown and HTML strings into a JSON Abstract Syntax Tree (AST).

import { parse } from 'micro-mdx-parser';

const markdownContent = `# Hello MDX-like!

This is a paragraph with **bold** text and an _italic_ word.

<p>HTML can also be parsed.</p>

<MyComponent prop="value" />
`;

const htmlContent = `<div><h1>Welcome</h1><p>This is <strong>some</strong> HTML.</p></div>`;

const parsedMarkdown = parse(markdownContent);
const parsedHtml = parse(htmlContent);

console.log('Parsed Markdown AST:');
console.log(JSON.stringify(parsedMarkdown, null, 2));

console.log('\nParsed HTML AST:');
console.log(JSON.stringify(parsedHtml, null, 2));

// Example of accessing elements
if (parsedMarkdown.length > 0 && parsedMarkdown[0].type === 'element' && parsedMarkdown[0].tagName === 'h1') {
  console.log('\nFirst element in Markdown is an H1:', parsedMarkdown[0].children[0].content);
}