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

Want to control how line breaks appear in your Markdown? The mdast-util-newline-to-break utility is your answer. This powerful tool converts simple line endings (enters) into <br> tags, giving you precise control over text rendering in your Markdown documents. Let's explore how this tiny utility can significantly impact your content presentation.

What is mdast-util-newline-to-break?

This utility processes an mdast (Markdown Abstract Syntax Tree) and replaces standard line breaks with hard breaks (<br>). It's the secret ingredient behind remark-breaks, simplifying Markdown transformations by handling the nitty-gritty details of line break conversion.

Why Use This Utility?

• Precise Control: Display user content exactly as authored, respecting every line ending.
• Enhanced Readability: Force line breaks where you intend, improving visual structure.
• Under-the-Hood Power: Used by remark-breaks, it’s a robust solution for complex Markdown workflows.

GitHub uses similar logic in comments and issues. While not semantically pure or compliant with standard Markdown (which uses trailing spaces or escapes!), it offers a pragmatic approach to preserving author intent.

Examples of Markdown Hard Breaks:

Markdown offers two standard methods for creating hard breaks:

• Trailing Spaces: Add two spaces at the end of a line.

  lorem␠␠
  ipsum
  

  Copy
• Backslash Escape: Use a backslash at the end of a line.

  lorem \
  ipsum
  

  Copy

If your audience is Markdown-savvy, documenting the escape method is recommended. However, for user-generated content, mdast-util-newline-to-break offers a more intuitive solution.

Installation

As an ESM (ECMAScript Module), installation is simple:

Node.js (v16+)

npm install mdast-util-newline-to-break

Deno

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

Browsers

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

Usage

Here’s a simple example demonstrating the functionality of mdast-util-newline-to-break with Node.js:

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 reads a Markdown file (example.md), transforms its AST to convert newlines to breaks, and then outputs the modified Markdown.

Key Features and Benefits

• newlineToBreak(tree) Function: The core of the package, processing your Markdown AST.
  • Accepts a single parameter: tree (a Node representing the Markdown AST).
  • Modifies the tree in place, replacing newline characters with <br> elements.
• Syntax Compatibility: Recognizes common newline characters (\r, \n, \r\n).
• Syntax Tree Integration: Adds standard mdast Break nodes to represent the hard breaks, ensuring compatibility with other mdast tools.
• TypeScript Ready: Fully typed for seamless integration with TypeScript projects.

remark-breaks and Related Tools

• remark-breaks: The most direct way to leverage this utility as a unified remark plugin.
• remark-gfm: Supports GitHub Flavored Markdown, including features like autolinking and tables.
• remark-github: Enhances Markdown by linking references to GitHub commits, issues, and users directly.

Contributing

Contributions are welcome! Refer to the contributing guidelines in the syntax-tree/.github repository for instructions on getting involved.

License

This project is licensed under the MIT license.