Search code examples
githubmarkdownnewlineread-the-docs

how to I preserve newlines while converting markdown from github to read-the-docs?

I am trying to convert some documentation from github to read-the-docs. I came across an interesting issue where my newlines (aka line breaks aka /n) are getting lost in conversion. this happens with tooltips AND with summary/details

how to get multilines summaries and tooltips in read-the-docs?

for example: my code inside github:

[tooltip_example_1]: ## "this is line 1 of my tooltip
this is line 2 of my tooltip"

this ia an example of [multiline tooltip][tooltip_example_1]


<details><summary> this is an example of a summary with multiple lines details </summary>
this is line 1 of my details.
    
this is line 2 of my details.
</details>

this is what it looks like in github with nice newlines.

enter image description here

but after building the pages in read-the-docs this is what it looks like:

tooltip tag is broken AND all my summary details on a single line

enter image description here

I tried to use /n, <brk>, etc...
I tried single and multiple empty lines... I tried to google some solutions but so far no clear explanations nor solutions. Ideally I would love to find a simple editor I could use to modify my read-the-docs directly as I am not specifically excited about github.

Solution

  • I'm not really familiar with Read the Docs and mkdocs, but my guess is that tooltip and <details> tag aren't converted into HTML the same way in GitHub vs mkdocs.

    Details tag

    For the <details> tag, you probably need to use HTML directly for more control. That means using <br> to force a line break or you could wrap you lines in 2 different <p> tags or even use a <ul> list.

    Multi-line Tooltip

    For the tooltip, it could be that mkdocs doesn't support multi-line tooltips. If that's the case, it would be good to raise an issue about that in the official GitHub repo.

    In the meantime, you could always try:

    [tooltip_example_2]: ## "this is line 1 of my tooltip&#10;this is line 2 of my tooltip"

this is an example of [multiline tooltip][tooltip_example_2]

    Note here the use of the use of a Decimal numeric character references to the line feed character (LF). This one works in GitHub, but I can't confirm if it works with mkdocs.