Trouble to handle line breaks

[l0th3r]

Hi, I am really new to Tex, LaTex and LuaTex.

I try to render a markdown file but it seems that HTML rendering doesn't work.
I also noticed that soft line breaks doesn't line break once rendered in Tex.

Any idea what I do wrong ?
Thanks in advance anyone.

test.tex

\documentclass{article}

\usepackage{markdown} % package to parse markdown

\markdownSetup{
	html=true,			% allow HTML recognition
	fencedCode=true,		% allow code blocks
	fancyLists=true,		% allow more ways to create lists
	texMathDollars=true,	% allow Tex dollar sign mathematical expression
	inlineNotes=true,	% allow inline notes
	pipeTables=true,		% allow markdown tables
	taskLists=true,		% allow task lists
	underscores=false,	% remove usage of underscores for emphasis
}

\begin{document}
	\markdownInput{content/example.md}
\end{document}

example.md

# This is an H1

## This is an H2

### This is an H3

<p>
  Hello<br>
  World!
</p>

Lorem ipsum dolor sit amet Lorem ipsum
dolor sit amet Lorem ipsum dolor sit amet

output:

[Witiko]

Thanks for using the Markdown package.

The html option only allows us to recognize HTML code in Markdown input instead of displaying it as regular text. However, since LaTeX has no support for displaying HTML code, we hide HTML code by default in PDF documents. If you use TeX4ht to produce e-books and websites, the HTML code is displayed, see the example document examples/latex-tex4ht.tex:

markdown/examples/latex-pdftex.tex

Lines 64 to 81 in e7c6a5b

	\begin{markdown}
	Here is some <b>HTML code</b> mixed *with Markdown*. In `\TeX`{=tex}, the HTML
	code will be silently ignored, whereas in `\TeX`{=tex}4ht, the HTML code will
	be passed through to the output:
	<table border="1">
	<tr>
	<td>Emil</td>
	<td>Tobias</td>
	<td>Linus</td>
	</tr>
	<tr>
	<td>16</td>
	<td>14</td>
	<td>10</td>
	</tr>
	</table>
	\end{markdown}

Typeset the document by running command make4ht --shell-escape latex-tex4ht.tex fn-in in directory examples/:

If you have a better idea of how the Markdown package should display HTML in PDF documents, let me know!

[Witiko]

Ping @michal-h21, the maintainer of TeX4ht and author of TeX4ht support in the Markdown Package for TeX, for brainstorming.

[michal-h21]

The original code seems to be rendered fine in HTML, when compiled using

 $ make4ht -lm draft test.tex

On a non-related note, I've finished my HTML parser for LuaXML. It is not on CTAN yet, but I will upload it before the TUG conference, where I will show its use. It can be used for HTML to TeX transformations, so it should be possible to use it for HTML rendering in Markdown.

[l0th3r]

Thank you a lot @Witiko and @michal-h21 for you replies.
I understand completely it make sense.

Actually, if I may, originally I did not wanted to use HTML, and added the option only so I could use <br> and/or manage the layout with HTML tags, since I have trouble understanding how line breaks are handled by the package. I tried to search in the documentation and found some things mentioning hard line breaks etc, but it's really confused for me.

The wanted behaviour for my project is for the markdown line breaks to be "as is" in Tex. Could you indicate how I could do that ?

Also thanks for indicating TeX4ht. I will make sure to explore it if I need to use more HTML features with the markdown package. For the wanted scope, it is overkill to use HTML in my project.

Thank you in advance for further reply.

[Witiko]

Actually, if I may, originally I did not wanted to use HTML, and added the option only so I could use <br> and/or manage the layout with HTML tags, since I have trouble understanding how line breaks are handled by the package. I tried to search in the documentation and found some things mentioning hard line breaks etc, but it's really confused for me.

You can type two or more spaces at the end of a line to write a line break:

foo␣␣
baz

Due to limitations of TeX, this does not work in \begin{markdown} ... \end{markdown}. However, if you save your document into a separate document document.md and input it with \markdownInput{document.md}, it should work fine.

---

Additionally, since Markdown 3.0.0 we also support CommonMark backslash line breaks:

foo\
baz

These should work both in \begin{markdown} ... \end{markdown} and with \markdownInput.

---

Finally, since Markdown 3.0.0, you may also render newlines as line breaks:

\markdownSetup {
  renderers = {
    softLineBreak = {\\},
  },
}
\begin{markdown}
foo
bar
\end{markdown}

Before Markdown 3.0.0, you would achieve the same result as follows:

\markdownSetup { hardLineBreaks }
\begin{markdown}
foo
bar
\end{markdown}

---

All the above examples should produce the following output:

foo
bar

[Witiko]

On a non-related note, I've finished my HTML parser for LuaXML. It is not on CTAN yet, but I will upload it before the TUG conference, where I will show its use. It can be used for HTML to TeX transformations, so it should be possible to use it for HTML rendering in Markdown.

That sounds awesome! 🥳

[l0th3r]

@Witiko Thank you again for your time I really appreciate it.

Alas, it doesn't work in my environment, even before writing this issue, I tried those methods.

My markdown is in a separate file: home.md

# Hello world
Lorem ipsum dolor sit amet Lorem ipsum\
dolor sit amet Lorem ipsum dolor sit amet

It produce:

Adding this to main.tex:

\markdownSetup {
  renderers = {
    softLineBreak = {\\},
  },
}

Generate and error :
! Package markdown Error: Renderer softLineBreak is undefined.

I wonder if I have something wrong with my work environment. Or I do not understand something ?

[Witiko]

Alas, it doesn't work in my environment, even before writing this issue, I tried those methods.

Both approaches that you mentioned are only available in Markdown 3, which was only released in TeX Live 2024 a couple months ago. It's likely that you are still using an older version of the Markdown package.

For older versions of the Markdown package, try changing home.md as follows:

# Hello world
Lorem ipsum dolor sit amet Lorem ipsum␣␣
dolor sit amet Lorem ipsum dolor sit amet

In the above code, I used the visible space characters (␣), which are more difficult to miss at a glance.
In home.md, you should replace them with regular space characters ( ).

Please, do let us know if this solves your issue. 😉

[l0th3r]

Please, do let us know if this solves your issue. 😉

Thank you again for your reply.
I understand, since I am not getting everything about "packages" usage with Tex environment, I did not even thought about it.

So rather than just fix the issue I would prefer to update the markdown package and use the latest features.
How can I achieve that ? Is is by upgrading LuaTex ? Or by upgrading tex-live
I did not installed the markdown package manually, it was present natively when installing LuaTex with the texlive-latex-extra apt package (I use Ubuntu).

Thank you in advance for your time.

[Witiko]

So rather than just fix the issue I would prefer to update the markdown package and use the latest features.
How can I achieve that ? Is is by upgrading LuaTex ? Or by upgrading tex-live
I did not installed the markdown package manually, it was present natively when installing LuaTex with the texlive-latex-extra apt package (I use Ubuntu).

Ubuntu and Debian are always behind the official release schedule of TeX Live by a lot. Currently, Ubuntu 22.04 LTS is 2.5 years behind, Ubuntu 23.10 is 1 year behind, and Ubuntu 24.04 LTS is a couple months behind, see packages.ubuntu.com. Ubuntu 24.04 LTS will likely receive Markdown 3 with the next update of the texlive-* packages in Q3 or Q4 of 2024.

The easiest way to update the Markdown package is to install the latest version manually, see section Installation of the user manual. This involves no compilation, just copying files to your home directory (for the local installation) or to the directory with your document (for the portable installation).

Alternatively, you can also install the latest TeX Live manually. This will allow you to keep packages up-to-date using the TeX package manager (tlmgr). You don't need to uninstall the TeX Live from Ubuntu, they can happily live side-by-side.

Finally, if you are comfortable with Docker, you can use the texlive/texlive Docker image, which includes Markdown 3.
This is how I do it.

[l0th3r]

The easiest way to update the Markdown package is to install the latest version manually, see section Installation of the user manual. This involves no compilation, just copying files to your home directory (for the local installation) or to the directory with your document (for the portable installation).

Thank you for your fast reply. I understand. The portable installation seems to be the best for me since me and some friends will be working on the documentation and everyone is on ubuntu for this project, meaning that with the portable installation, I just have to update the markdown package in our repository and everyone will be updated.

I tried to follow the portable installation. But now I have errors everywhere. when compiling my Tex file.

I cloned the repository, executed make base in the cloned directory and moved the lists of files as siblings of my .tex file as :

I tried test.tex :

\documentclass{article}
\usepackage{markdown}

\begin{document}
	\markdownInput{content/home.md}
\end{document}

output:

Thank you in advance for your time.

[Witiko]

I cloned the repository, executed make base in the cloned directory and moved the lists of files as siblings of my .tex file as: [...]

The file markdown.tex needs to be in a directory markdown/. This was done to allow users to name their own document markdown.tex, as discussed in #74. This information is present in the user manual but you are the second person I know of that missed this information. Therefore, we should probably highlight it.

[l0th3r]

The file markdown.tex needs to be in a directory markdown/. This was done to allow users to name their own document markdown.tex, as discussed in #74. This information is present in the user manual but you are the second person I know of that missed this information. Therefore, we should probably highlight it.

I feel stupid. It's actually pretty clear, it's just my bad, I am doing 20 things at the same time and it's not efficient.

It works fine, some things in my previous file is not working any more due to the update of the package, I will work on that and try my best to achieve it without taking more of your time, it should be fine.

I would like to thank you a lot for the time you took to help me and your work on the markdown package. You seem to be close to the community of your work and that's rare and precious that you take the time to reply without being annoyed by people being beginner. I will not hesitate to ask for more help if I am lost.

Thank you so much, I wish you the best.

[Witiko]

Thank you for taking the time to ask, it helps me to improve the documentation and come up with new ideas. If there are other parts of the Markdown package that don't make sense to you, feel free to ask either here or on our Discord and Matrix servers.