Transform Markdown Line Endings into Hard Breaks with mdast-util-newline-to-break

Want to display markdown content exactly as your users intended, preserving line breaks without messy escapes or spaces? mdast-util-newline-to-break is your solution. This powerful utility converts standard newline characters (\r, \n, \r\n) in your Markdown Abstract Syntax Tree (AST) into HTML <br> tags. Perfect for rendering user-generated content with fidelity.

Why Use mdast-util-newline-to-break?

• Preserve User Intent: Display content with line breaks exactly as users authored it, improving readability and visual appeal.
• Clean Markdown: Avoid cumbersome trailing spaces or escape characters to create hard breaks, resulting in cleaner, easier-to-maintain Markdown.
• Seamless Integration: Easily integrates with the remark ecosystem using remark-breaks.
• Standards Compliance: While technically not compliant with strict Markdown standards without escapes, this utility prioritizes user experience.

How it Works: Turning Newlines into <br> Tags

The mdast-util-newline-to-break package parses your Markdown AST, specifically targeting standard newline characters. When it encounters a newline, it inserts a <br> tag (represented as a Break node in the mdast tree) at that position within the document. This ensures that the rendered HTML will contain a hard break where the user intended.

Installation

As an ESM-only package, installing mdast-util-newline-to-break is straightforward:

npm install mdast-util-newline-to-break

For Deno:

import { newlineToBreak } from 'https://esm.sh/mdast-util-newline-to-break@2'

For Browsers:

<script type="module">
  import { newlineToBreak } from 'https://esm.sh/mdast-util-newline-to-break@2?bundle'
</script>

Usage: A Simple Example

Here’s how to use the utility in a Node.js environment:

import fs from 'node:fs/promises'
import { fromMarkdown } from 'mdast-util-from-markdown'
import { newlineToBreak } from 'mdast-util-newline-to-break'
import { toMarkdown } from 'mdast-util-to-markdown'

const doc = await fs.readFile('example.md')
const tree = fromMarkdown(doc)
newlineToBreak(tree)
console.log(toMarkdown(tree))

This code snippet reads a Markdown file, parses it into an AST, utilizes the newline to break utility to convert newlines to <br> tags, and then converts the modified AST back into Markdown.

API: newlineToBreak(tree)

The package exports a single identifier: newlineToBreak.

• newlineToBreak(tree): This function modifies the input tree (the mdast syntax tree) by replacing newline characters with Break nodes.
  • tree: The mdast tree you want to modify.

Why Not Use Spaces or Escapes?

While Markdown offers trailing spaces and escapes for hard breaks, these can be cumbersome for users. mdast-util-newline-to-break offers a more natural way for users to express line breaks in their content. If you want to support markdown line endings as hard breaks, this is exactly the right tool.

Here's a comparison:

Related Projects

• remark-breaks: A remark plugin that provides mdast-util-newline-to-break as a unified solution.
• remark-gfm: Support for GitHub Flavored Markdown (GFM).
• remark-github: Link references to commits, issues, and users, similar to GitHub.

Embrace Natural Line Breaks

mdast-util-newline-to-break empowers you to render markdown content more intuitively, respecting user-defined line breaks without sacrificing clean markdown syntax. Try it out today and elevate your user experience.