break

remark-github-break

remark plugin to turn normal line endings into hard breaks.

Contents

• What is this?
• When should I use this?
• Install
• Use
• API
  • remarkGithubBreak()
• Bugs
• Authoring
• HTML
• CSS
• Syntax
• Types
• Compatibility
• Security
• Related
• Contribute
• Notice
• License

What is this?

This plugin turns normal line endings (soft breaks) into <br> elements (hard breaks).

This behavior is specific to github.com that only work in comments, not in files.

This plugin is part of a monorepo rehype-github. See its readme for more info.

When should I use this?

You can use this plugin when you want to match how github.com works or when you want to build similar pipelines.

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. This is 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.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install remark-github-break

In Deno with esm.sh:

import remarkGithubBreak from 'https://esm.sh/remark-github-break@0'

In browsers with esm.sh:

<script type="module">
  import remarkGithubBreak from 'https://esm.sh/remark-github-break@0?bundle'
</script>

Use

Say our module example.js looks as follows:

import remarkGithubBreak from 'remark-github-break'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGithubBreak)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('Hello,\nworld!\n======')

console.log(String(file))

…now running node example.js yields:

<h1>Hello,<br>
world!</h1>

API

This package exports no identifiers. The default export is remarkGithubBreak.

remarkGithubBreak()

Plugin to turn normal line endings into hard breaks.

Bugs

GitHub performs this behavior in their parser (cmark-gfm), operating on the markdown, similar to how GFM is implemented as syntax extensions. That means that breaks only work in paragraphs and headings when authored with markdown, not with HTML.

This behavior being not semantic according to HTML can also be considered a bug.

Authoring

It’s recommended not to depend on this behavior.

HTML

The markup for breaks is:

<br>

CSS

No CSS is needed.

Syntax

Breaks form with the following BNF:

break ::= '\n'

Types

This package is fully typed with TypeScript. It exports no additional types.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 16+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified version 6+ and remark version 7+.

Security

This package is safe.

Related

• remark-gfm — support GFM in remark
• remark-breaks — same

Contribute

See contributing.md in rehypejs/.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.

Notice

This project is not affiliated with GitHub.

License

MIT © Titus Wormer