Line breaks in the markdown docs are translated as <br /> tags erroneously.

[thenickcox]

This has been bothering me about the docs for a while. I recently had a documentation PR merged in Marionette core, and part of that removed the line breaks in the docs because they were being converted to <br /> tags. But I was browsing the Markdown docs today, and a Markdown parser should only insert a <br /> tag if there are two line breaks. This is not the case on these docs; each single line break in the docs is parsed as a <br /> tag. (To verify, check the compiled HTML)

I did some digging and thought maybe it was an issue with marked, the markdown parsing library used to compile the docs here. So I made a Codepen to test some markdown with a line break in it, and it correctly renders as a space.

My conclusion at this point is that it's something in the compile-docs.js task. But nothing immediately jumps out to me as being at fault.

I'm filing this issue because I'm working on a PR for some docs, and I had been removing the line breaks so that they don't render as <br /> tags, but I'm now convinced that's not a great solution, because it makes them harder to read.

[samccone]

@thenickcox The only other piece of the process would be our fork of docco that @peterblazejewicz did.

@peterblazejewicz any thoughts?

[thenickcox]

Now that we're talking about it, there is a call in the getDescription method in the compile-docs.js that specifically replaces <br> tags, which shouldn't be necessary with marked's default output. It occurred to me to do the same thing in the compileContent call, but that feels hacky.

[samccone]

hmm open to ideas of fixes that you think can make it better, but yeah all of the docs require a bit of massaging to get "right"

[thenickcox]

I mean, if the core team thought that would be an acceptable fix, far be it from me to say otherwise. Let me know if you'd like me to submit a PR with that same function call (or abstracted to avoid duplication), and I'll go ahead with that.

[samccone]

@thenickcox that would be awesome!

[thenickcox]

Great. The only downside I could see to that is that any intentional <br> tag in the docs would get thrown out. We could add a check for a class like "no-replace" or something, but I don't think I've ever intentionally used a <br> in markdown.

[peterblazejewicz]

@samccone @thenickcox do compile-docs download only release-based content? So 2.4.1 tagged release content is downloaded, not the current docs from master - if that is true, the changes (line breaks and tweeks) from linked PR are not yet within compiled docs - I've check paragraphs, e.g.:
marionettejs/backbone.marionette@18d3227#diff-65e45658842b27540d8f45490a59c2fbL120

[thenickcox]

I'll look into this, but I wasn't able to get my dev environment running due to a jade compilation error.

[thenickcox]

Okay. Thanks to @peterblazejewicz's fix, I should be able to take a look at this tonight.