Add examples regarding new lines / line breaks

[stephanbogner]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)

---

Problem

I am struggling to work with new lines / line breaks and many others did in the past.

From what I've seen there are three problems:

1. Lack of knowledge about Markdown itself (e.g. double space before \n)
2. Missing knowledge about Markdown flavors / plugins (e.g. remark-breaks to turn soft line endings into hard breaks)
3. Problems with using the library itself

---

Solution

Regarding 1) and 2)

Could be solved/enhanced by mentioning it next to an appropriate example. Something like "Tip: Read up on how Markdown treats new lines and have a look at plugins such as remark-breaks that can change this behaviour."

Regarding 3)

I compiled a few ways to use markdown that I tried from which some failed, which I think also cause some of the confusion.

❌ Case 1

Doesn't work as expected (treats everything as the headline)

<ReactMarkdown>
    # I am headline 1

    The **bold brown fox** jumps over the _italic dog_
</ReactMarkdown>

HTML:

<h1>I am headline 1 The <strong>bold brown fox</strong> jumps over the <em>italic dog</em></h1>

✅ Case 2

Works as expected, but has a pitfall:
If a line in the markdown is indented with spaces it (rightfully) gets interpreted as a pre-tag.

const markdown = `# I am headline 1
    
The **bold brown fox** jumps over the _italic dog_`

[...]

<ReactMarkdown children={markdown}/>

HTML:

<h1>I am headline 1</h1>
<p>The <strong>bold brown fox</strong> jumps over the <em>italic dog</em></p>

✅ Case 3

Works as expected

const markdown="# I am headline 1  \n\n The **bold brown fox** jumps over the _italic dog_"

[...]

<ReactMarkdown children={markdown}/>

HTML:

<h1>I am headline 1</h1>
<p>The <strong>bold brown fox</strong> jumps over the <em>italic dog</em></p>

❌ Case 4:

Does not work as expected (treats everything as the headline)

<ReactMarkdown children="# I am headline 1  \n\n The **bold brown fox** jumps over the _italic dog_"/>

HTML:

<h1>I am headline 1  \n\n The <strong>bold brown fox</strong> jumps over the <em>italic dog</em></h1>

Solution

Would be cool to add another example regarding line breaks to the docs. Maybe case 3 with a note regarding the problem with case 4.

---

Alternatives

It's about a documentation enhancement so I don't think alternatives apply here.

[wooorm]

Your cases seem to have more to do with how JSX works. The JSX transform you use collapsed arbitrary whitespace. E.g., Babel repl.
Case 4 specifically has to do with that if you write the characters \n in JSX, as text or in an attribute, that’s just those characters.
If how JSX works is confusing to humans, I think it is fine to change the readme examples here and here.

[wooorm]

What do you propose?

I don‘t think this project needs to explain what markdown is and how it works. It already defers to other sources for that.

[stephanbogner]

Regarding JSX:
Honestly ... I've been working with JSX now many years but sometimes it's still confusing (especially now with Markdown thrown into the mix), so thanks for your clarifications!

Regarding proposal:
My thought was "Hey there are so many (closed) issues regarding line breaks, maybe the docs should be enhanced in that regard" ... but no change would be fine too.

But I'd add another example under examples:

---

Handling line breaks

import React from 'react'
import ReactMarkdown from 'react-markdown'
import ReactDom from 'react-dom'

ReactDom.render(
  <ReactMarkdown children={"# Example:  \n\n The **bold brown fox** jumps over the _italic dog_"}/>,
  document.body
)

Tip: We recommend learning how Markdown treats new lines and how plugins (such as remark-breaks) can alter this behavior.

[wooorm]

Having another example is fine, but I’m not sure about this heading, this code. I don’t think humans know that one of these 3 problems you describe (plus the line endings + JSX one) are solved by “Handling line breaks”. And there’s no explanation what the code does. Perhaps a new appendix is better. Say for example:

### Appendix A: line endings in markdown (and in JSX)

You might try to write markdown directly in your JSX and find that it **does
not** work:

```jsx
<ReactMarkdown>
  # Hi

  This is **not** a paragraph.
</ReactMarkdown>
```

The is because in JSX the whitespace (including line endings) is collapsed to
a single space.
So the above example is equivalent to:

```jsx
<ReactMarkdown> # Hi This is **not** a paragraph. </ReactMarkdown>
```

Instead, to pass markdown to `ReactMarkdown`, you can use the `children` prop
with a template literal:

```jsx
<ReactMarkdown
  children={`
# Hi

This is a paragraph.
  `}
/>
```

Template literals have another potential problem, because they keep whitespace
(including indentation) inside them.
That means that the following **does not** turn into a heading:

```jsx
<ReactMarkdown
  children={`
    # This is **not** a heading, it’s an indented code block
  `}
/>
```

Now, the hard breaks in markdown / hard breaks with remark-breaks thing is another point that perhaps can be discussed here.
But... I understand that folks sometimes want to use remark-breaks, but they are mostly wrong in doing so. https://github.com/remarkjs/remark-breaks#when-should-i-use-this

[stephanbogner]

Sorry for the slow reply – life stuff happening.

I think the bare minimum would be a working example like the one I proposed. A more extensive section like yours is even better. So from my end 👍

[zoora]

@wooorm thanks for the explanation about JSX , i was dealing with the same line break missing white space, probleme .