-
-
Notifications
You must be signed in to change notification settings - Fork 7.4k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
markup/goldmark: Enable pass-through of raw content blocks #10894
Comments
What is "LaTeX in Markdown"? If this is about adding yet another delimiter for this particular syntax, why not use a shortcode (for inline latex) and code fences for block latex? |
Hey @bep, Thanks for your reply! When I mentioned "LaTeX in Markdown," I was referring to the ability to include standard LaTeX expressions directly within Markdown files using the familiar dollar-sign syntax (single $ for inline and double $$ for block expressions). This is the standard syntax in Jekyll, Jupyter notebooks, VSCode Markdown extension, on platforms like GitHub, and more, making it a widely recognized and expected feature for many users. Shortcodes however require to change Markdown files for Hugo, which is not only inconvenient but prevents users from reusing the same Markdown files across projects. There's an in-depth discussion about this topic in the forum as well: https://discourse.gohugo.io/t/katex-in-hugo/43274 |
Miscellaneous thoughts... Display mode (blocks)This syntax is supported by GitHub:
This syntax is supported by GitLab:
The fenced code block syntax is consistent with Mermaid diagram support by both services:
Alternate delimitersKaTeX and MathJax support alternate delimiters:
These are not supported by either GitHub or GitLab. Markdown in the wild using this syntax is not portable to either service. Inline modeWith Hugo you must use a shortcode. The resulting markdown is not portable. Minor advantage of fenced code blocks and shortcodesJS and CSS can be loaded as needed (per page) without requiring a front matter flag (i.e., Alternative (opinion)For diagrams, I prefer to use the free Kroki service because it embeds an SVG---no client side rendering. For math, I prefer to use the free Math API service because it embeds an SVG---no client side rendering. The fenced code block syntax is portable; the shortcode syntax is not portable. |
I am sorry, if I do not understand the proposal. Does Hugo already support for |
Hugo itself does not recognize math stuff delimited by
Themes shipped with MathJax support (KaTeX or something else) will probably display But as a result of what I said before, taking
Also brings similar problems mentioned in #6694 #6864 #7249. These issues will be solved cleanly once |
Here is a brief survey on the status quo of different math block support among popular Markdown editors:
Note 1: GitHub markdown preview is also bugged, which does not treat contents inside
|
I think it'll be better if there's an way to configure the delimiters since Reference |
I don't understand this issue. I have LaTeX working properly in Hugo by loading Matjax JS. In a
Note that the config script lets you decide what delimiters you want. Then, on the |
This will fail:
Ampersands are converted |
Right, now that you mention it, I remember that I had to extend PHPMarkdown to discard LaTeX in order to handle those corner cases for WordPress. |
@erincatto You cannot enable arbitrary Goldmark extensions; only those that have been integrated. |
This: $$
\begin{array} {lcl}
L(p,w_i) &=& \dfrac{1}{N}\Sigma_{i=1}^N(\underbrace{f_r(x_2
\rightarrow x_1
\rightarrow x_0)G(x_1
\longleftrightarrow x_2)f_r(x_3
\rightarrow x_2
\rightarrow x_1)}_{sample\, radiance\, evaluation\, in\, stage2}
\\\\\\ &=&
\prod_{i=3}^{k-1}(\underbrace{\dfrac{f_r(x_{i+1}
\rightarrow x_i
\rightarrow x_{i-1})G(x_i
\longleftrightarrow x_{i-1})}{p_a(x_{i-1})}}_{stored\,in\,vertex\, during\,light\, path\, tracing\, in\, stage1})\dfrac{G(x_k
\longleftrightarrow x_{k-1})L_e(x_k
\rightarrow x_{k-1})}{p_a(x_{k-1})p_a(x_k)})
\end{array}
$$ Can be rewritten to: {{< raw >}}
\begin{array} {lcl}
L(p,w_i) &=& \dfrac{1}{N}\Sigma_{i=1}^N(\underbrace{f_r(x_2
\rightarrow x_1
\rightarrow x_0)G(x_1
\longleftrightarrow x_2)f_r(x_3
\rightarrow x_2
\rightarrow x_1)}_{sample\, radiance\, evaluation\, in\, stage2}
\\\\\\ &=&
\prod_{i=3}^{k-1}(\underbrace{\dfrac{f_r(x_{i+1}
\rightarrow x_i
\rightarrow x_{i-1})G(x_i
\longleftrightarrow x_{i-1})}{p_a(x_{i-1})}}_{stored\,in\,vertex\, during\,light\, path\, tracing\, in\, stage1})\dfrac{G(x_k
\longleftrightarrow x_{k-1})L_e(x_k
\rightarrow x_{k-1})}{p_a(x_{k-1})p_a(x_k)})
\end{array}
{{< /raw >}} Assuming there is a Am I missing something? |
Yes, you can you use shortcodes and render hooks to pass https://discourse.gohugo.io/tag/typesetting I don't see any downside. |
@bep the objection is that math prose often uses dozens of inline math blocks in a paragraph of text, many of whose .inner is just a few characters, and in this case such long short codes are tedious to type and read. It also adds a compatibility obstacle for importing and exporting to other systems that understand TeX-style math mode fences. In other words, the objection is to the verbosity of the short code fence for math-heavy text (tedious) and its difference from standard math fences (compatibility). |
How portable/standard is this?
|
It may look silly, but this sub-language of LaTeX has been standard math typesetting for at least 30 years. It predates the web. |
GitHub markdown using GitLab markdown using The long multiline example above is something I created as a worst case example,similar to the old browser "acid" test. It's portable to some systems but not to others. When authoring in things like Obsidian or Typora, the |
$$ is very portable. I'm able to paste it directly into a LaTeX document. (there are some bugs in that particular sequence though). I think shortcodes are fine for separate, displayed blocks of math. They are quite bad for inline math. It is common in mathematical writing to refer to many single character math symbols within a single sentence. Adding lots of inline shortcodes hurts readability for the author. |
Also, a shortcode that just prints This:
is rendered to this: <script>alert('pwned!')</script> With this proposal, the raw markdown between and including the delimiters is not cast to template.HTML, so Go's html/template package does its job. This:
is rendered to this: <p>$<script>alert('pwned');</script>$</p> When using a shortcode for this, site and theme authors need to remember to do this for their typesetting/LaTeX/math shortcode and render hook.
|
OK, I didn't know that GitHub/lab actually supported this. I have not read the entire discussion, but I assume that one such extension does not already exist for Hugo, and that:
I suggest we
If someone can help me with a name for this particular extension, I can create it and we can talk about who want to implement it. But the scope is |
1) There are no existing extensions that do what we need. Those that do exist exceed the scope of this proposal, are opinionated, and in some cases impede performance. 2) Yes, I think the Hugo project should maintain control over this. 3) Other projects that rely Goldmark may benefit from this. Its un-opinionated and generic implementation can be used with any JS package or renderer that needs to parse raw content... math, chemistry, physics, diagrams, etc. 4) The names of the core Goldmark extensions (maintained by yuin) are singular nouns. The best name that I have come up with so far is rawBlock, but others may have better ideas.
I'm not sure exactly what you mean, but the "blocks" that will bypass markdown processing may be inline, block, single line, or multiline. An important note is that the delimiters themselves are not swallowed; they are part of the "block". Finally, the proposed default configuration for this is: markup:
goldmark:
extensions:
rawBlock: # or a better name
enable: false
delimiters:
- ['$','$'] # inline equations
- ['$$','$$'] # block equations
- ['\(','\)'] # inline equations
- ['\[','\]'] # block equations |
It's the title of this issue, "raw content blocks". Is that the scope of this discussion?
|
IMO inline would need to be in scope as well as blocks. Maybe rawContent would be sufficiently expressive? |
Yes, as well as the other common/standard1 delimiting pairs as shown in the proposed default configuration above.
Note that block equations may have the delimiters on the same line, or on the preceding and following lines. I have not seen the two mixed. For example, I don't think we need to worry about these:
Footnotes |
OK, but then the name What about
I suspect that the implementation need to distinguish between block and inline delimiters, but time will tell. |
Perfect. |
OK, I have created https://github.com/gohugoio/hugo-goldmark-extensions -- I suggest we take implementation specific discussions somewhere inside that repo. |
This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs. |
Continuing the discussion from #10888 and the forum.
Hey everyone,
Following up on the PR, I wanted to open an issue to discuss an improvement to LaTeX support in Hugo. Standard LaTeX in Markdown support has been requested by the community for a while, especially among the scientific blogging community. However, Hugo only supports a special syntax that requires modifying existing Markdown files to work with Hugo. Platforms like GitHub already support the standard dollar-sign syntax, e.g. that's an inline expression:$x^2$ .
Here's the proposal:
This is already implemented here: janhuenermann@ad38246
Looking forward to hearing your thoughts on this!
The text was updated successfully, but these errors were encountered: