remark-breaks

remark-breaks is a small unified/remark plugin that converts every soft line ending in a Markdown paragraph into a hard break (<br>), matching how platforms like GitHub render comments, issues, and PRs even though it isn’t strictly compliant Markdown.

Normally Markdown requires trailing spaces or a backslash escape to force a line break; this plugin removes that requirement so user-authored content (chat messages, comments, freeform notes) renders visually the same way it was typed, without asking authors to learn Markdown’s hard-break syntax.

What You Get

• A one-line unified().use(remarkBreaks) integration that requires no configuration or options
• Enters converted to <br> in the rendered HTML output, matching GitHub-style comment/issue rendering
• Full TypeScript types shipped via @types/mdast and a generated index.d.ts
• ESM-only, tree-shakeable module with no runtime side effects (sideEffects: false)
• 100% test coverage enforced via c8 --100 in the test script

Common Use Cases

• Rendering user-submitted comments, chat messages, or notes where authors don’t know Markdown’s hard-break syntax
• Building a GitHub-comment-style preview pane that needs to match GitHub’s own line-break rendering behavior
• Any remark/unified-based content pipeline where preserving visual line structure matters more than strict CommonMark compliance
• Static site generators or CMSs that ingest freeform, loosely-formatted Markdown from non-technical authors

Under The Hood

Architecture The entire implementation is a ~15-line function in lib/index.js that returns a unified Transform: given the parsed mdast Root tree, it delegates the actual node rewriting to the separate mdast-util-newline-to-break package, which finds soft breaks and reclassifies them as hard break nodes. This plugin exists purely as unified/remark glue around that utility — it owns no parsing or serialization logic itself, which is idiomatic for the unified ecosystem’s compose-many-small-plugins design.

Tech Stack Pure ESM JavaScript (type: module) with TypeScript types generated via tsc --build rather than hand-written, plus @types/mdast for the tree type definitions. Depends on unified (^11) and mdast-util-newline-to-break (^2) as its only runtime dependencies. Uses xo (ESLint preset) and prettier for style, and remark-cli/remark-preset-wooorm to lint its own documentation.

Code Quality test.js runs fixture-based tests (input Markdown → expected HTML) covering variations like zero/one/two/three trailing spaces and \r line endings, run through a real remark-parse → remarkBreaks → remark-rehype → rehype-stringify pipeline rather than mocks. Coverage is enforced at 100% via c8 --100, and the package also runs type-coverage to guarantee full type coverage on every build — a high quality bar for a project this small.

API Design The API is a single default export with zero configuration options or arguments: unified().use(remarkBreaks) is the entire integration surface. This no-config design is the norm for narrowly-scoped unified plugins and keeps the learning curve essentially zero — the tradeoff is no per-use customization if a consumer wanted, e.g., a different break tag.