Mdast Util From Markdown

https://github.com/syntax-tree/mdast-util-from-markdown
Admin
A utility that takes markdown input and turns it into an mdast syntax tree, used for manually...
Tokens:28,321
Snippets:434
Trust Score:9.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install mdast-util-from-markdown

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

Installation command for Node.js environments.

```sh
npm install mdast-util-from-markdown
```

--------------------------------

### Start buffering output

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Initiates capturing of output for the current context.

```typescript
this.buffer()
```

--------------------------------

### Image Handler Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of an image syntax into an mdast image node.

```text
Input: ![alt text](image.png "Title")
Output: {
  type: 'image',
  url: 'image.png',
  alt: 'alt text',
  title: 'Title'
}
```

--------------------------------

### Configure fromMarkdown options

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Example usage of the Options interface to provide GFM and frontmatter extensions.

```typescript
const options: Options = {
  extensions: [micromarkGfmExtension()],
  mdastExtensions: [
    mdastGfmExtension(),
    [mdastFrontmatterExtension()]
  ]
}

const tree = fromMarkdown(markdown, options)
```

--------------------------------

### Link Handler Examples

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of regular links and link references into their respective mdast nodes.

```text
Input: [text](http://example.com "Title")
Output: {
  type: 'link',
  url: 'http://example.com',
  title: 'Title',
  children: [{type: 'text', value: 'text'}]
}
```

```text
Input: [text][id]
Output: {
  type: 'linkReference',
  identifier: 'id',
  label: 'id',
  referenceType: 'full',
  children: [{type: 'text', value: 'text'}]
}
```

--------------------------------

### Strong Handler Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of strong text into an mdast strong node.

```text
Input: **strong**
Output: {type: 'strong', children: [{type: 'text', value: 'strong'}]}
```

--------------------------------

### Definition Handler Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of a link reference definition into an mdast definition node.

```text
Input: [id]: http://example.com "Title"
Output: {
  type: 'definition',
  identifier: 'id',
  label: 'id',
  url: 'http://example.com',
  title: 'Title'
}
```

--------------------------------

### Implement a custom Extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Example configuration object demonstrating how to handle token entry, exit, and tree transformations.

```typescript
const mathExtension = {
  canContainEols: ['mathFlow'],
  enter: {
    mathFlow: function(token) {
      this.enter({type: 'mathFlow', value: ''}, token)
    },
    mathFlowData: function(token) {
      // Data handler
    }
  },
  exit: {
    mathFlow: function(token) {
      this.exit(token)
    }
  },
  transforms: [tree => {
    // Transform the tree after parsing
    return tree
  }]
}
```

--------------------------------

### Definition handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Example of handling definition components like label, destination, and title.

```typescript
const extension = {
  exit: {
    definitionLabel(token) {
      const label = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.label = label
      node.identifier = normalizeIdentifier(this.sliceSerialize(token))
    },
    definitionDestination(token) {
      const url = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.url = url
    },
    definitionTitle(token) {
      const title = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.title = title
    }
  }
}
```

--------------------------------

### Token Stack Trace Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Visualizes the token stack state during nested token processing.

```javascript
tokenStack: [[{type: 'paragraph'}, undefined]]
tokenStack: [[{type: 'paragraph'}, undefined], [{type: 'strong'}, undefined]]
// On exit, pop both token and corresponding node from stack
```

--------------------------------

### Emphasis Enter Handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Example implementation of an enter handler for emphasis tokens.

```javascript
function emphasisEnter(token) {
  this.enter({type: 'emphasis', children: []}, token)
}
```

--------------------------------

### Autolink Protocol Handling Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Demonstrates the transformation of a URL autolink into a link node with children.

```javascript
Input: <http://example.com>
Output: {
  type: 'link',
  url: 'http://example.com',
  children: [{type: 'text', value: 'http://example.com'}]
}
```

--------------------------------

### Define Markdown Input

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

Example markdown content used for parsing.

```markdown
## Hello, *World*!
```

--------------------------------

### Parse Markdown to mdast

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

Basic usage example showing how to read a file and convert it into an mdast tree.

```js
import fs from 'node:fs/promises'
import {fromMarkdown} from 'mdast-util-from-markdown'

const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc)

console.log(tree)
```

--------------------------------

### Inspect mdast Output

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

The resulting syntax tree structure generated from the example markdown.

```js
{
  type: 'root',
  children: [
    {
      type: 'heading',
      depth: 2,
      children: [
        {type: 'text', value: 'Hello, '},
        {type: 'emphasis', children: [{type: 'text', value: 'World'}]},
        {type: 'text', value: '!'}
      ]
    }
  ]
}
```

--------------------------------

### Indented code block examples

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/test/fixtures/code-indented.md

Demonstrates basic indentation for code blocks using spaces.

```markdown
    indented code
```

```markdown
    more indented code
```

--------------------------------

### Create a strikethrough extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

A practical example of implementing enter and exit handlers for a custom syntax construct.

```typescript
const strikethroughExtension = {
  enter: {
    strikethrough(token) {
      this.enter({type: 'strikethrough', children: []}, token)
    }
  },
  exit: {
    strikethrough(token) {
      this.exit(token)
    }
  }
}
```

--------------------------------

### Emphasis Handler Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of emphasized text into an mdast emphasis node.

```text
Input: *emphasis*
Output: {type: 'emphasis', children: [{type: 'text', value: 'emphasis'}]}
```

--------------------------------

### AST Stack Trace Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Visualizes the stack state changes during the parsing of bold and italic markdown syntax.

```javascript
// Building: **bold _italic_**
stack: [root]
stack: [root, paragraph]
stack: [root, paragraph, strong]
stack: [root, paragraph, strong, emphasis]
// Text nodes added to emphasis.children
stack: [root, paragraph, strong]
stack: [root, paragraph]
stack: [root]
```

--------------------------------

### Resume and get buffered content

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Stops capturing and returns the stringified content.

```typescript
const text = this.resume()
```

--------------------------------

### Inline Code Handler Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the transformation of inline code syntax into an mdast inlineCode node.

```text
Input: `code`
Output: {type: 'inlineCode', value: 'code'}
```

--------------------------------

### Handle Fragments in Code Fencing

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Example implementation of using buffer and resume methods to handle code fencing tokens.

```javascript
enter: {
  codeFenced(token) {
    this.enter({type: 'code'}, token)
    this.buffer()  // Push fragment
  }
},
exit: {
  codeFencedInfo(token) {
    const lang = this.resume()  // Pop fragment, stringify
    // ... process lang
    this.buffer()  // Push new fragment for code value
  }
}
```

--------------------------------

### Transform Type Definition and Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Defines a function signature for transforming the mdast tree and provides a basic implementation example.

```typescript
type Transform = (tree: Root) => Root | null | undefined | void
```

```typescript
const transform: Transform = (tree) => {
  // Visit and modify nodes
  return tree
}
```

--------------------------------

### Character Escape Handling Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows how escaped characters are processed into literal text nodes.

```javascript
Input: \*not emphasized\*
Output: {type: 'text', value: '*not emphasized*'}
```

--------------------------------

### List item handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Example of handling list item values by parsing the serialized token.

```typescript
function handleListItemValue(token) {
  if (this.data.expectingFirstListItemValue) {
    const list = this.stack[this.stack.length - 2]
    const value = this.sliceSerialize(token)
    list.start = Number.parseInt(value)
    this.data.expectingFirstListItemValue = undefined
  }
}
```

--------------------------------

### Implement a Handle function

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Example implementation of a Handle function that enters a custom node into the compilation context.

```typescript
const handle: Handle = function(token) {
  this.enter({type: 'customNode'}, token)
}
```

--------------------------------

### Emphasis Exit Handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Example implementation of an exit handler for emphasis tokens, including state finalization.

```javascript
function emphasisExit(token) {
  const value = this.resume()  // If buffering
  const node = this.stack[this.stack.length - 1]
  node.value = value  // Finalize property
  this.exit(token)
}
```

--------------------------------

### Line Ending Preservation Example

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Illustrates how line endings are preserved within nodes that support them, such as paragraphs.

```javascript
canContainEols: ['paragraph']

Input: a\nb
Output: {type: 'text', value: 'a\nb'} (line ending preserved)
```

--------------------------------

### Implement Handles mapping

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Example of a Handles object mapping specific token types like codeText and emphasis to handler functions.

```typescript
const handlers: Handles = {
  codeText: function(token) {
    this.enter({type: 'inlineCode', value: ''}, token)
  },
  emphasis: function(token) {
    this.enter({type: 'emphasis', children: []}, token)
  }
}
```

--------------------------------

### Catching Token Mismatch Errors

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Example of catching and identifying token mismatch errors during the parsing process.

```typescript
try {
  const tree = fromMarkdown(markdown, {mdastExtensions: [customExt]})
} catch (error) {
  if (error.message.includes("it's not open")) {
    console.error('Token mismatch error:', error.message)
  }
}
```

--------------------------------

### Handle List Item Values

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Parses and assigns the starting value of a list item when the context expects it.

```typescript
function listItemValue(token) {
  if (this.data.expectingFirstListItemValue) {
    const list = this.stack[this.stack.length - 2]
    list.start = Number.parseInt(this.sliceSerialize(token))
    this.data.expectingFirstListItemValue = undefined
  }
}
```

--------------------------------

### Link reference handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Example of transforming a link node into a linkReference node based on parsing state.

```typescript
const extension = {
  exit: {
    link(token) {
      const node = this.stack[this.stack.length - 1]
      
      if (this.data.inReference) {
        node.type = 'linkReference'
        node.referenceType = this.data.referenceType || 'shortcut'
        delete node.url
        delete node.title
      }
      
      delete node.identifier
      delete node.label
      
      this.exit(token)
    }
  }
}
```

--------------------------------

### Text data handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Example of handling text data by appending serialized tokens to a text node.

```typescript
function handleTextData(token) {
  const parent = this.stack[this.stack.length - 1]
  
  // Get or create text node
  let text = parent.children[parent.children.length - 1]
  if (!text || text.type !== 'text') {
    text = {type: 'text', value: ''}
    parent.children.push(text)
    this.stack.push(text)
  }
  
  // Append serialized token
  text.value += this.sliceSerialize(token)
}

// Exit handler pops the text node
function exitTextData(token) {
  this.stack.pop()
}
```

--------------------------------

### Token Close Error Message

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Example of the error message thrown when a closing token does not match the open token on the stack.

```text
Error: Cannot close `emphasis` (1:3-1:5): it's not open
```

--------------------------------

### Configure Extensions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Initializes the configuration by merging multiple markdown extensions.

```javascript
configure(config, mdastExtensions)
```

--------------------------------

### enter(node, token, onError?)

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Pushes a node onto the stack and records the opening token.

```APIDOC
## enter(node, token, onError?)

### Description
Adds the node to the parent's children, pushes it onto the stack as the new parent, and records the opening token. Position tracking is initialized with the token's start position.

### Parameters
- **node** (Nodes) - Required - The AST node to enter
- **token** (Token) - Required - The micromark token triggering this enter
- **onError** (OnEnterError) - Optional - Handler for when this node doesn't close properly
```

--------------------------------

### View Project File Structure

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/README.md

Displays the directory layout of the documentation files.

```text
output/
├── README.md                      ← You are here
├── INDEX.md                       ← Navigation hub
├── REFERENCE.md                   ← Quick reference
├── MANIFEST.md                    ← Documentation info
├── types.md                       ← Type definitions
├── architecture.md                ← Internal design
├── extending.md                   ← Extension guide
├── default-handlers.md            ← Built-in handlers
├── errors.md                      ← Error reference
└── api-reference/
    ├── fromMarkdown.md            ← Main function
    ├── CompileContext.md          ← Handler context
    ├── Extension.md               ← Extension interface
    ├── Options.md                 ← Configuration
    └── Handle.md                  ← Handler type
```

--------------------------------

### CompileContext enter method

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Pushes a node onto the stack and records the opening token.

```typescript
enter(this: CompileContext, node: Nodes, token: Token, onError?: OnEnterError | null | undefined): undefined
```

--------------------------------

### Configure the compiler factory

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Initializes the compiler configuration by merging default handlers with provided mdast extensions.

```javascript
const config = {
  transforms: [],
  canContainEols: ['emphasis', 'fragment', 'heading', 'paragraph', 'strong'],
  enter: { /* default enter handlers */ },
  exit: { /* default exit handlers */ }
}

configure(config, (options || {}).mdastExtensions || [])
```

--------------------------------

### Project File Structure

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Overview of the directory layout for the mdast-util-from-markdown package.

```text
mdast-util-from-markdown/
├── dev/
│   ├── index.d.ts          # Public type definitions
│   └── lib/
│       ├── index.js        # Core implementation
│       └── types.d.ts      # Internal types
├── index.d.ts              # Type definitions (production)
├── index.js                # Production code
├── package.json
├── readme.md
└── license
```

--------------------------------

### Run Node.js with Development or Production Conditions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Use the --conditions flag to toggle between development mode (with assertions) and production mode (stripped assertions).

```bash
node --conditions development example.js
```

```bash
node --conditions production example.js
```

--------------------------------

### Enable Development Mode

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Command to run scripts with development conditions enabled for internal state assertions.

```bash
node --conditions development script.js
```

--------------------------------

### buffer()

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Creates a new fragment node on the stack to capture subsequent content.

```APIDOC
## buffer()

### Description
Pushes a temporary `Fragment` node onto the stack. Subsequent handlers will add content to this fragment. When `resume()` is called, the fragment's content is serialized and removed from the stack.

### Signature
`buffer(this: CompileContext): undefined`
```

--------------------------------

### Merge Extension Logic

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Demonstrates how individual extension properties are merged into the main configuration object. Later extensions override earlier ones.

```javascript
// For each extension
config.enter = {...config.enter, ...extension.enter}
config.exit = {...config.exit, ...extension.exit}
config.canContainEols = [...config.canContainEols, ...extension.canContainEols]
config.transforms = [...config.transforms, ...extension.transforms]
```

--------------------------------

### Visualize Context Stack Evolution

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Illustrates the state of the stack as tokens are entered and exited during markdown parsing.

```javascript
// For markdown: **bold _italic_**
// Stack evolution:

// 1. Enter paragraph
[root, paragraph]

// 2. Enter strong
[root, paragraph, strong]

// 3. Enter emphasis
[root, paragraph, strong, emphasis]

// 4. Enter text node
[root, paragraph, strong, emphasis, text]

// 5. Exit text
[root, paragraph, strong, emphasis]

// 6. Exit emphasis
[root, paragraph, strong]

// 7. Exit strong
[root, paragraph]

// 8. Exit paragraph
[root]
```

--------------------------------

### Package.json Configuration

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Key fields in package.json defining exports, entry points, and type definitions.

```json
{
  "name": "mdast-util-from-markdown",
  "type": "module",
  "exports": {
    "development": "./dev/index.js",
    "default": "./index.js"
  },
  "main": "./index.js",
  "types": "./index.d.ts"
}
```

--------------------------------

### Visualize Documentation File Relationships

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/MANIFEST.md

A tree-like representation of the documentation file structure and dependencies.

```text
INDEX.md (navigation hub)
  ├─ REFERENCE.md (quick reference)
  │   └─ api-reference/fromMarkdown.md (basic API)
  │       └─ api-reference/Options.md (configuration)
  │           └─ api-reference/Extension.md (extensions)
  │
  ├─ extending.md (extension guide)
  │   └─ api-reference/CompileContext.md (handler context)
  │       └─ api-reference/Handle.md (handler patterns)
  │
  ├─ types.md (all type definitions)
  │   └─ api-reference/*.md (for examples)
  │
  ├─ architecture.md (internal design)
  │   └─ default-handlers.md (handler examples)
  │
  └─ errors.md (error reference)
      └─ extending.md (debugging patterns)
```

--------------------------------

### Handle configuration errors

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Wrap fromMarkdown calls in a try-catch block to handle errors resulting from invalid extension configurations.

```typescript
try {
  const tree = fromMarkdown(markdown, {
    mdastExtensions: [invalidExtension]
  })
} catch (error) {
  console.error('Configuration error:', error.message)
}
```

--------------------------------

### resume()

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Stops capturing in a fragment and returns its stringified content.

```APIDOC
## resume()

### Description
Pops the topmost node from the stack and converts it to a string using `mdast-util-to-string`. Used to extract accumulated text content from buffered sections.

### Returns
- **string** - The serialized text content of the topmost (fragment) node on the stack.
```

--------------------------------

### Define the fromMarkdown entry point

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

The primary public API function for orchestrating the markdown to AST conversion process.

```typescript
export function fromMarkdown(value, encoding, options)
```

--------------------------------

### Implement Simple Open/Close Pattern

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Standard pattern for constructs that enter on open and exit on close.

```typescript
const extension = {
  enter: {
    strong(token) {
      this.enter({type: 'strong', children: []}, token)
    }
  },
  exit: {
    strong(token) {
      this.exit(token)
    }
  }
}
```

--------------------------------

### Implement Enter Handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Pattern for initializing a node when entering a token.

```typescript
enter: {
  tokenType(token) {
    this.enter({type: 'nodeType', children: []}, token)
  }
}
```

--------------------------------

### Import in Deno

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

Importing the package via esm.sh for Deno projects.

```js
import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2'
```

--------------------------------

### Import in Browsers

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/readme.md

Importing the package via esm.sh for browser-based modules.

```html
<script type="module">
  import {fromMarkdown} from 'https://esm.sh/mdast-util-from-markdown@2?bundle'
</script>
```

--------------------------------

### Manage Buffer and Resume

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Always pair buffer calls with resume to ensure content is correctly extracted and the stack remains aligned.

```typescript
enter: {
  fencedCode: function(token) {
    this.enter({type: 'code'}, token)
    this.buffer()  // Start capturing
  }
},
exit: {
  fencedCode: function(token) {
    const code = this.resume()  // Stop capturing and get content
    const node = this.stack[this.stack.length - 1]
    node.value = code
    this.exit(token)
  }
}
```

--------------------------------

### Implement Enter Phase Handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Used to create and push a new node onto the AST stack when a token opens.

```typescript
const extension = {
  enter: {
    emphasis(token) {
      // Create and enter a new emphasis node
      this.enter({type: 'emphasis', children: []}, token)
    }
  }
}
```

--------------------------------

### Implement a custom block extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Use buffer and resume methods to capture and assign content like titles to custom block nodes.

```typescript
const noteExtension = {
  enter: {
    noteStart(token) {
      this.enter({type: 'note', title: '', children: []}, token)
      this.buffer()
    },
    noteTitle(token) {
      // Title is buffered
    }
  },
  exit: {
    noteTitle(token) {
      const title = this.resume()
      const note = this.stack[this.stack.length - 1]
      note.title = title
    },
    noteStart(token) {
      this.exit(token)
    }
  }
}
```

--------------------------------

### Configure GFM Extensions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Use both micromark and mdast extensions to enable GFM support.

```typescript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension as gfmMicromark} from 'micromark-extension-gfm'
import {gfmExtension as gfmMdast} from 'mdast-util-gfm'

const markdown = '| Heading |\n|--------|\n| Cell   |'

const tree = fromMarkdown(markdown, {
  extensions: [gfmMicromark()],
  mdastExtensions: [gfmMdast()]
})
```

--------------------------------

### Create a Debug Extension Wrapper

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Wraps existing extension handlers to log entry and exit events with token positions.

```typescript
function createDebugExtension(extension) {
  return {
    ...extension,
    enter: Object.entries(extension.enter || {}).reduce((acc, [key, handler]) => {
      acc[key] = function(token) {
        console.log(`Entering ${key} at`, token.start)
        return handler.call(this, token)
      }
      return acc
    }, {}),
    exit: Object.entries(extension.exit || {}).reduce((acc, [key, handler]) => {
      acc[key] = function(token) {
        console.log(`Exiting ${key} at`, token.end)
        return handler.call(this, token)
      }
      return acc
    }, {})
  }
}
```

--------------------------------

### Implement Enter Handlers

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

Map micromark token types to functions that initialize nodes on the stack.

```typescript
const extension: Extension = {
  enter: {
    emphasis: function(token) {
      this.enter({type: 'emphasis', children: []}, token)
    },
    strong: function(token) {
      this.enter({type: 'strong', children: []}, token)
    },
    customSyntax: function(token) {
      this.enter({type: 'customNode'}, token)
    }
  }
}
```

--------------------------------

### Integration Test Custom Syntax

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Shows how to test custom syntax parsing by passing an extension to fromMarkdown.

```typescript
test('custom syntax parsing', () => {
  const markdown = '~~strikethrough~~'
  const tree = fromMarkdown(markdown, {
    mdastExtensions: [strikethroughExtension]
  })
  
  const node = tree.children[0].children[0]
  assert.equal(node.type, 'strikethrough')
  assert.equal(node.children[0].value, 'strikethrough')
})
```

--------------------------------

### Configure parsing options as a variable

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Define extensions and mdastExtensions in a standalone object before passing to fromMarkdown.

```typescript
const parseOptions: Options = {
  extensions: [/* ... */],
  mdastExtensions: [/* ... */]
}

const tree = fromMarkdown(markdown, parseOptions)
```

--------------------------------

### Add GitHub Flavored Markdown Support

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Integrates GFM support by providing both micromark and mdast extensions.

```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension as gfmMicromark} from 'micromark-extension-gfm'
import {gfmExtension as gfmMdast} from 'mdast-util-gfm'

const tree = fromMarkdown(markdown, {
  extensions: [gfmMicromark()],
  mdastExtensions: [gfmMdast()]
})
```

--------------------------------

### Implement an inline construct with properties

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Capture inline content using buffering to populate node properties like titles.

```typescript
const tooltipExtension = {
  enter: {
    tooltip(token) {
      this.enter(
        {type: 'tooltip', children: [], title: ''},
        token
      )
    },
    tooltipTitle(token) {
      this.buffer()
    }
  },
  exit: {
    tooltipTitle(token) {
      const title = this.resume()
      const tooltip = this.stack[this.stack.length - 1]
      tooltip.title = title
    },
    tooltip(token) {
      this.exit(token)
    }
  }
}
```

--------------------------------

### Visualize Token Stack

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Tracks the currently open tokens during the parsing process.

```text
[[{type: 'paragraph'}, undefined]]
[[{type: 'paragraph'}, undefined], [{type: 'emphasis'}, undefined]]
↑ Tracks which tokens are open
```

--------------------------------

### Implement a reference-based construct

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Capture reference keys from tokens to populate node data.

```typescript
const citationExtension = {
  enter: {
    citation(token) {
      this.enter({type: 'citation', key: ''}, token)
      this.buffer()
    }
  },
  exit: {
    citation(token) {
      const key = this.resume()
      const citation = this.stack[this.stack.length - 1]
      citation.key = key
      this.exit(token)
    }
  }
}
```

--------------------------------

### fromMarkdown(markdown, options)

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

Configures the markdown parser with custom extensions to handle specific syntax tokens.

```APIDOC
## fromMarkdown(markdown, options)

### Description
Parses markdown content into an mdast tree using optional extensions to handle custom syntax.

### Parameters
- **markdown** (string) - The markdown source text to parse.
- **options** (object) - Configuration object.
  - **mdastExtensions** (Array) - An array of extension objects or nested arrays of extensions to be flattened and applied during parsing.

### Usage Example
```typescript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension} from 'mdast-util-gfm'

const tree = fromMarkdown('text', {
  mdastExtensions: [gfmExtension()]
})
```
```

--------------------------------

### Enter a node with enter()

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Adds a node to the parent's children and pushes it onto the stack.

```typescript
function emphasisEnter(token) {
  this.enter({type: 'emphasis', children: []}, token)
}
```

```typescript
function enter(token) {
  this.enter({type: 'customNode', children: []}, token, function(left, right) {
    // left: token that tried to close (or undefined if EOF)
    // right: this token (still open)
    // Handle the mismatch
  })
}
```

--------------------------------

### Import library types

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/README.md

Access core TypeScript interfaces and types for building extensions or custom handlers.

```typescript
import type {
  Extension,
  CompileContext,
  Options,
  Handle
} from 'mdast-util-from-markdown'
```

--------------------------------

### Documentation Directory Structure

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/INDEX.md

Visual representation of the documentation file hierarchy.

```text
output/
├── REFERENCE.md                 ← Start here
├── INDEX.md                     ← This file
├── types.md                     ← All type definitions
├── architecture.md              ← Internal design
├── extending.md                 ← Extension guide
├── default-handlers.md          ← Built-in handler reference
├── errors.md                    ← Error handling
└── api-reference/
    ├── fromMarkdown.md          ← Main API
    ├── CompileContext.md        ← Handler context
    ├── Extension.md             ← Extension interface
    ├── Options.md               ← Configuration
    └── Handle.md                ← Handler function type
```

--------------------------------

### Implement Handler with Buffering

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Pattern for capturing token content between enter and exit events.

```typescript
enter: {
  code(token) {
    this.enter({type: 'code', value: ''}, token)
    this.buffer()
  }
},
exit: {
  code(token) {
    const value = this.resume()
    this.stack[this.stack.length - 1].value = value
    this.exit(token)
  }
}
```

--------------------------------

### Unit Test Custom Extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Demonstrates a basic unit test for a custom mdast extension using node:test and assert.

```typescript
import test from 'node:test'
import assert from 'node:assert'
import {fromMarkdown} from 'mdast-util-from-markdown'

test('custom extension', () => {
  const ext = {
    enter: {
      myToken(token) {
        this.enter({type: 'myNode'}, token)
      }
    },
    exit: {
      myToken(token) {
        this.exit(token)
      }
    }
  }
  
  const tree = fromMarkdown('test', {mdastExtensions: [ext]})
  
  assert.equal(tree.children.length, 1)
  assert.equal(tree.children[0].type, 'myNode')
})
```

--------------------------------

### Setext Heading Output

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the resulting mdast node for a Setext-style heading.

```text
Input:
Hello
=====

Output node:
  {type: 'heading', depth: 1, children: [...]}
```

--------------------------------

### Buffer content with buffer()

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Pushes a temporary fragment node onto the stack to capture subsequent content.

```typescript
function onEnterFenced(token) {
  this.enter({type: 'code', lang: '', meta: '', value: ''}, token)
  this.buffer()  // Start capturing fence info
}
```

--------------------------------

### Implement type-safe configuration

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Use the Options type to define a wrapper function that merges custom extensions with user-provided options.

```typescript
import type {Options} from 'mdast-util-from-markdown'

function parseMarkdown(content: string, opts?: Options) {
  return fromMarkdown(content, {
    mdastExtensions: [basicExtension],
    ...opts
  })
}
```

--------------------------------

### Parse Full-Featured Markdown

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Integrates GFM, frontmatter, math, and MDX extensions simultaneously.

```typescript
import {gfmExtension as gfmMicromark} from 'micromark-extension-gfm'
import {mathExtension as mathMicromark} from 'micromark-extension-math'
import {mdxExtension as mdxMicromark} from 'micromark-extension-mdx'
import {gfmExtension as gfmMdast} from 'mdast-util-gfm'
import {frontmatterExtension} from 'mdast-util-frontmatter'
import {mathExtension as mathMdast} from 'mdast-util-math'
import {mdxExtension as mdxMdast} from 'mdast-util-mdx'

const tree = fromMarkdown(markdown, {
  extensions: [
    gfmMicromark(),
    mathMicromark(),
    mdxMicromark()
  ],
  mdastExtensions: [
    gfmMdast(),
    [
      frontmatterExtension(['yaml']),
      mathMdast(),
      mdxMdast()
    ]
  ]
})
```

--------------------------------

### CompileContext resume method

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Stops capturing in the current fragment and returns its stringified content.

```typescript
resume(this: CompileContext): string
```

--------------------------------

### Access stacks

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Inspect the current node and token stacks.

```typescript
const currentNode = this.stack[this.stack.length - 1]
const currentToken = this.tokenStack[this.tokenStack.length - 1][0]
```

--------------------------------

### Implement Buffer Pattern for Structured Content

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/extending.md

Use this pattern to accumulate content into a single string property rather than creating child nodes. Requires calling buffer() on enter and resume() on exit.

```typescript
const codeExtension = {
  enter: {
    code(token) {
      // Create node and push
      this.enter({type: 'code', lang: '', value: ''}, token)
      // Start buffering language info
      this.buffer()
    },
    codeLanguage(token) {
      // Language content is buffered
    }
  },
  exit: {
    codeLanguage(token) {
      // Extract buffered language
      const lang = this.resume()
      const codeNode = this.stack[this.stack.length - 1]
      codeNode.lang = lang
      
      // Resume buffering code value
      this.buffer()
    },
    code(token) {
      // Extract buffered code
      const value = this.resume()
      const codeNode = this.stack[this.stack.length - 1]
      codeNode.value = value
      
      // Pop the code node
      this.exit(token)
    }
  }
}
```

--------------------------------

### fromMarkdown(value, encoding?, options?)

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/fromMarkdown.md

Parses markdown content into an mdast Root node. Supports both string and Uint8Array inputs with optional encoding and configuration options.

```APIDOC
## fromMarkdown(value, encoding?, options?)

### Description
Parses markdown content into an mdast syntax tree. This function wraps micromark tokenization and applies the CommonMark specification by default.

### Parameters
- **value** (Value: string | Uint8Array) - Required - The markdown content to parse.
- **encoding** (Encoding) - Optional - Character encoding when value is a Uint8Array. Defaults to 'utf8'.
- **options** (Options) - Optional - Configuration object for parsing behavior and extensions.

### Return Type
- **Root** - An mdast Root node representing the parsed document, including position metadata.

### Usage Example
```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'

const tree = fromMarkdown('# Hello world')
```
```

--------------------------------

### Configure mdastExtensions in fromMarkdown

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

Pass an array of extensions to the mdastExtensions option to enable additional markdown syntax support.

```typescript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension} from 'mdast-util-gfm'
import {mathExtension} from 'mdast-util-math'

const markdown = '# Hello\n\n$$x = y$$'

const tree = fromMarkdown(markdown, {
  mdastExtensions: [
    gfmExtension(),
    mathExtension()
  ]
})
```

--------------------------------

### Apply Multiple Extensions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Combine multiple micromark and mdast extensions for complex parsing requirements.

```typescript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension} from 'mdast-util-gfm'
import {mathExtension} from 'mdast-util-math'
import {mdxExtension} from 'mdast-util-mdx'

const markdown = `
---
# Heading
| Table | Here |
|-------|------|
| Cell  | Cell |

$$math = equation$$

export const name = 'value'
`

const tree = fromMarkdown(markdown, {
  extensions: [
    gfmMicromark(),
    mathMicromark(),
    mdxMicromark()
  ],
  mdastExtensions: [
    gfmExtension(),
    mathExtension(),
    mdxExtension()
  ]
})
```

--------------------------------

### Define a code block extension with metadata in TypeScript

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

Demonstrates buffering content to capture language and metadata fields within a fenced code block.

```typescript
const codeBlockExtension: Extension = {
  canContainEols: ['codeMeta'],
  enter: {
    codeFenced: function(token) {
      this.enter({type: 'code', lang: '', meta: '', value: ''}, token)
      this.buffer()
    },
    codeFencedInfo: function(token) {
      // Buffering language
    }
  },
  exit: {
    codeFencedInfo: function(token) {
      const lang = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.lang = lang
      this.buffer()  // Start capturing meta
    },
    codeFencedMeta: function(token) {
      const meta = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.meta = meta
      this.buffer()  // Start capturing value
    },
    codeFenced: function(token) {
      const value = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.value = value
      this.exit(token)
    }
  }
}
```

--------------------------------

### Push node to stack

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Handle.md

Use enter to add a new node to the current stack.

```typescript
this.enter({type: 'emphasis', children: []}, token)
```

--------------------------------

### Define a Minimal Extension Handler

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

A basic implementation of enter and exit hooks for a custom token type.

```typescript
const myExtension = {
  enter: {
    myToken(token) {
      this.enter({type: 'myNode'}, token)
    }
  },
  exit: {
    myToken(token) {
      this.exit(token)
    }
  }
}
```

--------------------------------

### Ordered List Node Output

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the resulting mdast node for an ordered list.

```text
Input:
1. First
2. Second

Output:
{
  type: 'list',
  ordered: true,
  start: 1,
  children: [
    {type: 'listItem', children: [...]},
    {type: 'listItem', children: [...]}
  ]
}
```

--------------------------------

### Use Uint8Array Input

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

Supports parsing binary data by providing a Uint8Array and specifying the encoding.

```javascript
const buffer = new TextEncoder().encode('**Bold text**')
const tree = fromMarkdown(buffer, 'utf8')
```

--------------------------------

### Execute Tree Transforms

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Iterates through configuration transforms to modify the syntax tree.

```javascript
index = -1
while (++index < config.transforms.length) {
  tree = config.transforms[index](tree) || tree
}
```

--------------------------------

### Implement Handler with Buffering

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Uses buffer and resume methods to capture and process nested token content.

```typescript
const codeExtension = {
  enter: {
    codeFenced(token) {
      this.enter({type: 'code', lang: '', value: ''}, token)
      this.buffer()
    },
    codeFencedInfo(token) {
      // Info is buffered
    }
  },
  exit: {
    codeFencedInfo(token) {
      const lang = this.resume()
      this.stack[this.stack.length - 1].lang = lang
      this.buffer()  // Start capturing code value
    },
    codeFenced(token) {
      const value = this.resume()
      this.stack[this.stack.length - 1].value = value
      this.exit(token)
    }
  }
}
```

--------------------------------

### Extend the parser with custom syntax

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/README.md

Define custom enter and exit handlers to process specific tokens and integrate them into the mdast tree.

```typescript
const myExtension = {
  enter: {
    myToken(token) {
      this.enter({type: 'myNode'}, token)
    }
  },
  exit: {
    myToken(token) {
      this.exit(token)
    }
  }
}

const tree = fromMarkdown(markdown, {
  mdastExtensions: [myExtension]
})
```

--------------------------------

### Parse Basic Markdown

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/REFERENCE.md

The primary entry point for converting a Markdown string into an mdast tree.

```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'

const tree = fromMarkdown('# Hello\n\nThis is a paragraph.')
console.log(tree)
```

--------------------------------

### Resume capturing with resume()

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Stops capturing in a fragment and returns its stringified content.

```typescript
function onExitCodeFenceInfo(token) {
  const lang = this.resume()  // Get accumulated fence language
  const node = this.stack[this.stack.length - 1]
  node.lang = lang
}
```

--------------------------------

### Apply Single mdast Extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Options.md

Pass a single mdast extension to handle specific syntax like frontmatter.

```typescript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {frontmatterExtension} from 'mdast-util-frontmatter'

const markdown = '---\ntitle: Example\n---\n\nContent'

const tree = fromMarkdown(markdown, {
  mdastExtensions: [frontmatterExtension(['yaml'])]
})
```

--------------------------------

### CompileContext buffer method

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

Creates a new fragment on the stack to capture buffered output.

```typescript
buffer(this: CompileContext): undefined
```

--------------------------------

### Create enter handlers with opener

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Generates a handler that pushes a node onto the stack, optionally executing an additional function.

```typescript
function opener(create, and) {
  return function open(token) {
    enter.call(this, create(token), token)
    if (and) and.call(this, token)
  }
}
```

```javascript
atxHeading: opener(heading)
blockQuote: opener(blockQuote)
codeFenced: opener(codeFlow, buffer)  // Also calls buffer()
```

--------------------------------

### Implement Exit Handlers

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

Map micromark token types to functions that finalize nodes and pop them from the stack.

```typescript
const extension: Extension = {
  exit: {
    emphasis: function(token) {
      this.exit(token)
    },
    codeFenced: function(token) {
      const value = this.resume()
      const node = this.stack[this.stack.length - 1]
      node.value = value
      this.exit(token)
    }
  }
}
```

--------------------------------

### Extend Markdown Parsing

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/fromMarkdown.md

Using mdast extensions to support additional syntax features like GFM or frontmatter.

```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension} from 'mdast-util-gfm'

const markdown = '| Header |\n|--------|\n| Cell   |'
const tree = fromMarkdown(markdown, {
  mdastExtensions: gfmExtension()
})
```

```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'
import {gfmExtension} from 'mdast-util-gfm'
import {frontmatterExtension} from 'mdast-util-frontmatter'

const markdown = '---\ntitle: Hello\n---\n\n# Content'
const tree = fromMarkdown(markdown, {
  mdastExtensions: [
    gfmExtension(),
    frontmatterExtension(['yaml'])
  ]
})
```

```javascript
import {fromMarkdown} from 'mdast-util-from-markdown'

const markdown = 'Some text'
const tree = fromMarkdown(markdown, {
  extensions: [/* micromark extensions */],
  mdastExtensions: [/* mdast extensions */]
})
```

--------------------------------

### Fixing Token Mismatch in Extensions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Ensuring proper matching of enter and exit calls within custom extension handlers.

```typescript
const extension = {
  enter: {
    myToken(token) {
      this.enter({type: 'myNode'}, token)  // Must call enter
    }
  },
  exit: {
    myToken(token) {
      this.exit(token)  // Must call exit with same token type
    }
  }
}
```

--------------------------------

### Extension

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/types.md

The Extension interface is a configuration object used to extend the markdown parsing behavior. It allows defining handlers for token entry and exit, specifying nodes that can contain line endings, and providing tree transformation functions.

```APIDOC
## Extension

### Description
Configuration object for extending markdown parsing behavior.

### Properties
- **canContainEols** (Array<string>) - Optional - List of node types that can contain line endings as content.
- **enter** (Handles) - Optional - Object mapping token types to handlers called on token enter.
- **exit** (Handles) - Optional - Object mapping token types to handlers called on token exit.
- **transforms** (Array<Transform>) - Optional - Array of functions to transform the final tree.

### Usage Example
```typescript
const mathExtension = {
  canContainEols: ['mathFlow'],
  enter: {
    mathFlow: function(token) {
      this.enter({type: 'mathFlow', value: ''}, token)
    }
  },
  exit: {
    mathFlow: function(token) {
      this.exit(token)
    }
  },
  transforms: [tree => {
    return tree
  }]
}
```
```

--------------------------------

### exit(token, onError?)

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Pops the current node from the stack and finalizes its position.

```APIDOC
## exit(token, onError?)

### Description
Pops a node from the stack and the corresponding token from the token stack. Sets the node's end position from the token. Throws if there's a token type mismatch between the exiting token and the currently open token.

### Parameters
- **token** (Token) - Required - The micromark token that closes this node
- **onError** (OnExitError) - Optional - Handler for mismatched closing tokens
```

--------------------------------

### ATX Heading Token Events

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Displays the sequence of token events generated for an ATX-style heading and the resulting mdast node structure.

```text
Input: ## Hello
Token events:
  ['enter', {type: 'atxHeading'}]
  ['enter', {type: 'atxHeadingSequence'}]
  ['exit', {type: 'atxHeadingSequence'}]
  ['enter', {type: 'text'}, ...]
  ['exit', {type: 'text'}, ...]
  ['exit', {type: 'atxHeading'}]

Output node:
  {type: 'heading', depth: 2, children: [{type: 'text', value: 'Hello'}]}
```

--------------------------------

### Accessing Configuration Handlers

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/CompileContext.md

Accessing the merged configuration object to retrieve enter handlers and transforms.

```typescript
const handlers = this.config.enter  // Access all enter handlers
const transforms = this.config.transforms  // Access all transforms
```

--------------------------------

### Paragraph Node Output

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/default-handlers.md

Shows the resulting mdast node for a standard paragraph.

```text
Input: This is a paragraph.
Output: {type: 'paragraph', children: [{type: 'text', value: 'This is a paragraph.'}]}
```

--------------------------------

### Inspect Tree Structure with unist-util-visit

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/errors.md

Traverses the generated tree to log node types and their parents during debugging.

```typescript
import {visit} from 'unist-util-visit'

try {
  const tree = fromMarkdown(markdown, options)
  
  visit(tree, (node, index, parent) => {
    console.log('Node:', node.type, 'Parent:', parent?.type)
  })
} catch (error) {
  console.error('Parse failed:', error.message)
}
```

--------------------------------

### Define Extension Interface

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/api-reference/Extension.md

The base structure for defining custom markdown parsing behavior.

```typescript
interface Extension {
  canContainEols?: Array<string> | null | undefined
  enter?: Handles | null | undefined
  exit?: Handles | null | undefined
  transforms?: Array<Transform> | null | undefined
}
```

--------------------------------

### Orchestrate the parsing pipeline

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Key operations performed within the fromMarkdown function to process input and compile tokens.

```javascript
parse(options)          // Create micromark parser
  .document()           // Parse as document
  .write(preprocess()   // Preprocess input
         (value, encoding, true))
postprocess(...)        // Normalize token stream
compiler(options)(...)  // Compile tokens to tree
```

--------------------------------

### Optimize list insertions

Source: https://github.com/syntax-tree/mdast-util-from-markdown/blob/main/_autodocs/architecture.md

Uses array rebuilding for large lists to avoid O(n) splice performance penalties.

```javascript
if (insertions.length <= SMALL_LIST_LIMIT) {
  // O(n*k) splices for few insertions
  for (each insertion reversed) {
    events.splice(at, 0, event)
  }
} else {
  // O(n + k) rebuild for many insertions
  rebuild array with insertions
  events.splice(start, range, ...replacement)
}
```
Tokens:
Raw