Giter Club home page Giter Club logo

remark-breaks's Introduction

remark-breaks

Build Coverage Downloads Size Sponsors Backers Chat

remark plugin to support hard breaks without needing spaces or escapes (turns enters into <br>s).

Contents

What is this?

This package is a unified (remark) plugin to turn soft line endings (enters) into hard breaks (<br>s)

When should I use this?

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.

Install

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>

Use

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>

API

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

unified().use(remarkBreaks)

Support hard breaks without needing spaces or escapes (turns enters into <br>s).

Parameters

There are no parameters.

Returns

Transform (Transformer).

Syntax

This plugin looks for markdown line endings (\r, \n, and \r\n) preceded by zero or more spaces and tabs.

Syntax tree

This plugin adds mdast Break nodes to the syntax tree. These are the same nodes that represent breaks with spaces or escapes.

Types

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

Compatibility

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+.

Security

Use of remark-breaks does not involve rehype (hast) or user content so there are no openings for cross-site scripting (XSS) attacks.

Related

Contribute

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.

License

MIT © Titus Wormer

remark-breaks's People

Contributors

pd4d10 avatar remcohaszing avatar wooorm avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

remark-breaks's Issues

Heading line breaks only render using alternative syntax

Initial checklist

Affected packages and versions

3.0.2

Link to runnable example

https://codesandbox.io/s/remark-breaks-bug-example-by1dli

Steps to reproduce

Code Snippet:

import ReactMarkdown from "react-markdown";
import remarkBreaks from "remark-breaks";

const markdown = `
# Test h1 with
a linebreak

Test h1 with
a linebreak
===========

Test h2 with
a linebreak
-----------

## Test h2 with
a linebreak

Test paragraph with
a linebreak
`;

export default function App() {
  return (
    <div className="App">
      <ReactMarkdown remarkPlugins={[remarkBreaks]} children={markdown} />
    </div>
  );
}

Expected behavior

Should render (whitespace added for readability)

<h1>Test h1 with<br />a linebreak</h1>
<h1>Test h1 with<br />a linebreak</h1>

<h2>Test h2 with<br />a linebreak</h2>
<h2>Test h2 with<br />a linebreak</h2>

<p>Test pagaraph with<br />a linebreak</p>

Actual behavior

It instead renders (whitespace added for readability)

<h1>Test h1 with</h1>
<p>a linebreak</p>
<h1>Test h1 with<br />a linebreak</h1>

<h2>Test h2 with<br />a linebreak</h2>
<h2>Test h2 with</h2>
<p>a linebreak</p>

<p>Test pagaraph with<br />a linebreak</p>

How to prevent the break under definition lists

Initial checklist

Problem

A definition list should provide lazy continuation in markdown. example doc.

For instance, the package remark-definition-list is a remark plugin for creating definition lists for markdown files supporting lazy continuation like below:

Term 1

: Definition bla bla
with lazy continuation.

So, the definition above in markdown should not break.

Possible Solution

If one of the parent/grand parents type is a descriptiondetails or descriptionterm or descriptionlist, the text node will be omitted without break.

You can have a look at the sample markdown AST for definition lists. here

Maybe, the plugin can provide an option (optional) to provide the parent types in an array which is going to be omitted, like {omit: ["descriptiondetails", "descriptionterm", "descriptionlist"]} for giving flexibility to developers.

Doesn't cover headings.

Initial checklist

Problem

## Line 1
  Line 2

Line 1
Line 2
---------

These don't add <br>. Not sure if I'm using it wrong, works on others eg. unordered list

Would be great to have. Headings use breaks just as much as other nodes do.

Solution

It's a short function, so I did read it, but I don't know how unified, remark etc. work, so I'm guessing the issue is that it visits tree for 'text'

Alternatives

Workaround

# Line 1
# Line 2
<style> h1:nth-child... // of-type...

Flag for not collapsing new lines / blank lines / newlines / blanklines

As of now remark (as well as markdown spec) collapse all blank lines between paragraphs.
If you have:

This is a
paragraph.




This is another
paragraph.

You would get:

<p>This is a<br>
paragraph.</p>
<p>This is another<br>
paragraph.</p>```

Would be great if remark-brakes took some flag which would instead result in:

```html
<p>This is a<br>
paragraph.</p>
</br>
</br>
</br>
</br>
<p>This is another<br>
paragraph.</p>

If you can point out what should be done will try to provide PR (if desired),

thanks!

Breaks are not applied inside a table cell

Initial checklist

Affected packages and versions

lastest (3.0.2)

Link to runnable example

https://stackblitz.com/edit/github-4rc9wa

Steps to reproduce

  • Add two spaces at the end of a text inside a table cell and type some text on the next line
    |a|b|c| |--|--|--| |d|e|This paragraph should have a <br>|

Expected behavior

  • The text should be rendered with a
    inside the cell

image

Actual behavior

The text of the 2nd line is considered as a new td in a new tr
image

Runtime

No response

Package manager

No response

OS

No response

Build and bundle tools

No response

Move transformer into `mdast-util-breaks`

Initial checklist

Problem

The transformer can work on the AST without unified. It may be useful to use this as a plain function.

Solution

Move the transformer into a new package mdast-util-breaks. This package would be part of syntax-tree.

Alternatives

I chose the name to match the name remark-breaks, but it may make sense to use something more verbose, e.g.: mdast-util-break-newlines.

unist-util-visit missing in dependencies

This upsets Yarn 2, currently need this in .yarnrc.yml as a workaround:

packageExtensions:
  "remark-breaks@*":
    dependencies:
      "unist-util-visit": "*"

Skipping the template since this isn't an "unexpected behavior" type of bug.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.