remark plugin to support hard breaks without needing spaces or escapes
(turns enters into <br>
s).
- What is this?
- When should I use this?
- Install
- Use
- API
- Syntax
- Syntax tree
- Types
- Compatibility
- Security
- Related
- Contribute
- License
This package is a unified (remark) plugin to turn soft line endings
(enters) into hard breaks (<br>
s)
This plugin is useful if you want to display user content closer to how it was
authored, because when a user includes a line ending, itโll show as such.
GitHub does this in a few places (comments, issues, PRs, and releases), but itโs
not semantic according to HTML and not compliant to markdown.
Markdown already has two ways to include hard breaks, namely trailing spaces and
escapes (note that โ
represents a normal space):
loremโ โ
ipsum
lorem\
ipsum
Both will turn into <br>
s.
If you control who authors content or can document how markdown works, itโs
recommended to use escapes instead.
This package is ESM only. In Node.js (version 16+), install with npm:
npm install remark-breaks
In Deno with esm.sh
:
import remarkBreaks from 'https://esm.sh/remark-breaks@4'
In browsers with esm.sh
:
<script type="module">
import remarkBreaks from 'https://esm.sh/remark-breaks@4?bundle'
</script>
Say we have the following file example.md
(note: there are no spaces after
a
):
Mars is
the fourth planet
โฆand a module example.js
:
import rehypeStringify from 'rehype-stringify'
import remarkBreaks from 'remark-breaks'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {read} from 'to-vfile'
import {unified} from 'unified'
const file = await unified()
.use(remarkParse)
.use(remarkBreaks)
.use(remarkRehype)
.use(rehypeStringify)
.process(await read('example.md'))
console.log(String(file))
โฆthen running node example.js
yields:
<p>Mars is<br>
the fourth planet</p>
๐ Note: Without
remark-breaks
, youโd get:<p>Mars is the fourth planet</p>
This package exports no identifiers.
The default export is remarkBreaks
.
Support hard breaks without needing spaces or escapes (turns enters into
<br>
s).
There are no parameters.
Transform (Transformer
).
This plugin looks for markdown line endings (\r
, \n
, and \r\n
) preceded
by zero or more spaces and tabs.
This plugin adds mdast Break
nodes to the syntax tree.
These are the same nodes that represent breaks with spaces or escapes.
This package is fully typed with TypeScript. It exports no additional types.
Projects maintained by the unified collective are compatible with maintained versions of Node.js.
When we cut a new major release, we drop support for unmaintained versions of
Node.
This means we try to keep the current release line, remark-breaks@^4
,
compatible with Node.js 16.
This plugin works with unified
version 6+ and remark
version 7+.
Use of remark-breaks
does not involve rehype (hast) or user
content so there are no openings for cross-site scripting (XSS)
attacks.
remark-gfm
โ support GFM (autolink literals, footnotes, strikethrough, tables, tasklists)remark-github
โ link references to commits, issues, and users, in the same way that GitHub doesremark-directive
โ support directivesremark-frontmatter
โ support frontmatter (YAML, TOML, and more)remark-math
โ support math
See contributing.md
in remarkjs/.github
for ways
to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
MIT ยฉ Titus Wormer