{"id":11292,"library":"mdast-util-to-nlcst","title":"mdast to nlcst Transformer","description":"mdast-util-to-nlcst is a utility in the unifiedjs ecosystem that transforms an mdast (markdown abstract syntax tree) into an nlcst (natural language concrete syntax tree). Currently at stable version 7.0.1, the package follows a semver release cadence with notable breaking changes often accompanying major version bumps. Its core function is to allow inspection of the natural language content within markdown documents by providing a structured NLCST representation. Unlike other utilities like `mdast-util-to-hast` which converts markdown to HTML, this package focuses specifically on language processing. It is frequently used in conjunction with natural language parsers like `parse-english` or `parse-latin` and is wrapped by the `remark-retext` plugin for a higher-level abstraction. A key limitation is that it does not provide functionality to apply changes from the NLCST back into the original mdast tree.","status":"active","version":"7.0.1","language":"javascript","source_language":"en","source_url":"https://github.com/syntax-tree/mdast-util-to-nlcst","tags":["javascript","unist","mdast","mdast-util","nlcst","nlcst-util","util","utility","markdown","typescript"],"install":[{"cmd":"npm install mdast-util-to-nlcst","lang":"bash","label":"npm"},{"cmd":"yarn add mdast-util-to-nlcst","lang":"bash","label":"yarn"},{"cmd":"pnpm add mdast-util-to-nlcst","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as the Parser argument for natural language processing, or an alternative such as `parse-latin`.","package":"parse-english","optional":false},{"reason":"The `file` argument must be a VFile corresponding to the mdast tree, providing crucial positional information.","package":"to-vfile","optional":false},{"reason":"Commonly used to generate the initial mdast tree from markdown input, which is then passed to `toNlcst`.","package":"mdast-util-from-markdown","optional":false}],"imports":[{"note":"The package is ESM-only since v5.0.0. CommonJS `require` will result in an `ERR_REQUIRE_ESM` error.","wrong":"const toNlcst = require('mdast-util-to-nlcst')","symbol":"toNlcst","correct":"import { toNlcst } from 'mdast-util-to-nlcst'"},{"note":"TypeScript types are shipped with the package for configuring the `toNlcst` function.","symbol":"Options","correct":"import type { Options } from 'mdast-util-to-nlcst'"},{"note":"`parse-english` (and `parse-latin`) are named exports and must be imported correctly. This is a critical dependency for the `Parser` argument of `toNlcst`.","wrong":"import ParseEnglish from 'parse-english'","symbol":"ParseEnglish","correct":"import { ParseEnglish } from 'parse-english'"}],"quickstart":{"code":"import { fromMarkdown } from 'mdast-util-from-markdown'\nimport { toNlcst } from 'mdast-util-to-nlcst'\nimport { ParseEnglish } from 'parse-english'\nimport { read } from 'to-vfile'\nimport { inspect } from 'unist-util-inspect'\nimport { VFile } from 'vfile'\n\nasync function processMarkdown() {\n  // Simulate reading a markdown file\n  const markdownContent = 'Some *foo*sball.\\n\\nA second sentence.'\n  const file = new VFile({\n    path: 'example.md',\n    value: markdownContent\n  })\n\n  // Convert markdown string to mdast tree\n  const mdast = fromMarkdown(file.value.toString(), { \n    // Extensions might be needed for full markdown features, but not for basic text.\n  })\n\n  // Ensure the mdast tree has positional information, which `fromMarkdown` usually provides.\n  // The `file` object is crucial here as `toNlcst` expects it.\n  const nlcst = toNlcst(mdast, file, ParseEnglish)\n\n  // Inspect the resulting nlcst tree\n  console.log(inspect(nlcst))\n}\n\nprocessMarkdown().catch(console.error)\n","lang":"typescript","description":"Demonstrates converting markdown content from a VFile into an mdast tree, then transforming it into an nlcst tree using `ParseEnglish`, and inspecting the resulting natural language AST."},"warnings":[{"fix":"Ensure your project's `package.json` correctly resolves `mdast-util-to-nlcst` imports (e.g., in bundlers) and update all related `@types` and `vfile` dependencies to their latest compatible versions. Avoid using private APIs.","message":"Version 7.0.0 changed to use `export` maps, which affects how packages are resolved. It also requires updating `@types/mdast`, `@types/nlcst`, and `vfile` to compatible versions.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Upgrade your Node.js environment to version 14.14 or newer. Update your natural language parsers (e.g., `parse-english`, `parse-latin`) to their latest versions to match the new API.","message":"Version 6.0.0 dropped support for Node.js 12. The package now requires Node.js 14.14+ or later. Additionally, the API for parser libraries like `parse-latin` and `parse-english` changed, requiring updates to those packages.","severity":"breaking","affected_versions":">=6.0.0"},{"fix":"Migrate your project to use ES modules (`import`/`export`) or use a bundler that transpiles ESM to CommonJS if strictly necessary.","message":"Version 5.0.0 transitioned the package to be ESM-only. CommonJS `require()` statements will no longer work and will throw an `ERR_REQUIRE_ESM` error.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure that the mdast tree is generated from a source that provides positional data (e.g., `mdast-util-from-markdown` with a `VFile`) and always pass a valid `VFile` object as the second argument to `toNlcst`.","message":"The `toNlcst` function requires the input `tree` to have positional information (e.g., line, column, offset) and the `file` argument to be a `VFile` instance that corresponds to that tree. If this information is missing or inconsistent, the transformation may fail or produce incorrect NLCST.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Understand that `mdast-util-to-nlcst` is a one-way transformation. If you need to modify markdown based on natural language analysis, you will need to implement a separate process to map nlcst changes back to mdast or work directly on the mdast tree using other utilities.","message":"This utility is designed for transforming mdast to nlcst for analysis purposes. There is currently no official way to apply changes made to the nlcst tree back into the original mdast tree.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Change `const { toNlcst } = require('mdast-util-to-nlcst')` to `import { toNlcst } from 'mdast-util-to-nlcst'` and ensure your project is configured for ES modules (e.g., `\"type\": \"module\"` in `package.json` or using a bundler).","cause":"Attempting to use `mdast-util-to-nlcst` with CommonJS `require()` syntax.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: .../node_modules/mdast-util-to-nlcst/index.js"},{"fix":"Ensure the parser is imported using named imports: `import { ParseEnglish } from 'parse-english'` (not `import ParseEnglish from 'parse-english'`).","cause":"Incorrectly importing the natural language parser (e.g., `parse-english`) as a default export instead of a named export.","error":"TypeError: ParseEnglish is not a constructor"},{"fix":"Upgrade your Node.js environment to version 14.14 or higher. The unified collective generally maintains compatibility with active LTS Node.js versions.","cause":"Running `mdast-util-to-nlcst` (v6.0.0+) on an unsupported Node.js version.","error":"Your environment is not supported: `mdast-util-to-nlcst` requires Node.js `14.14` or later"},{"fix":"Ensure your mdast tree is generated by a parser that includes positional data (like `mdast-util-from-markdown`). Always provide a valid `VFile` object as the `file` argument, which typically holds the original source content and its associated positional data.","cause":"`toNlcst` was called with a `tree` lacking positional information or a `file` that is not a proper `VFile` instance.","error":"TypeError: Cannot read properties of undefined (reading 'position') or similar errors related to VFile."}],"ecosystem":"npm"}