Implement passthrough extension

[j2kun]

Continuing from gohugoio/hugo#10894

I'm happy to take a first pass at the implementation

[jmooring]

Notes...

1. This is a stand alone implementation, independent of Hugo.

2. Integration with Hugo is the second step, to be implemented as a PR in the Hugo repository.

3. This is probably a good starting point for test cases:

   git clone --single-branch -b hugo-github-issue-10894 https://github.com/jmooring/hugo-testing hugo-github-issue-10894
   cd hugo-github-issue-10894
   hugo server
   

4. The four delimiter pairs must work on the same line as the pass-through content, or on the preceding/following lines, but not mixed. For example, these shall not be passed-through:

   $inline
   $
   
   $$block
   $$
   

[bep]

My 50 cents. As to the config struct, I think it makes sense to start out with the delimiters @jmooring posted in another thread.

delimiters:
          - ['$','$']    # inline equations
          - ['$$','$$']  # block equations
          - ['\(','\)']  # inline equations
          - ['\[','\]']  # block equations

• I suspect you need/want to split these into block/inline (as the inline/block parsers in Goldmark are two separate things)
• We should add a default HTML renderer for this, but it would also be useful to export whatever new AST kinds (2?) we come up with.

@jmooring if would be great if you could somehow manage this issue, but just shout if you need my attention.

[jmooring]

you could somehow manage this issue

Will do, leaving initial implementation to @j2kun.

[j2kun]

The four delimiter pairs must work on the same line as the pass-through content, or on the preceding/following lines, but not mixed.

Not sure I understand what's being asked for here. May an inline equation be split across lines within a paragraph?

This is an example of an inline equation split across lines: $\sum_{x = 3}^10
x^2 = 3x + 5$. Should this be allowed?

This seems fine to me, and if so, I don't see why the following wouldn't be feasible (or why the implementation would be any different)

This is an example of an inline equation split across lines: $\sum_{x = 3}^10 x^2 = 3x + 5
$. Should this be allowed?

[jmooring]

Should this be allowed?

I don't think so, but test against other implementations (GitHub gist, GitLab snippet).

With a GitHub gist this is OK:

Inline $x = {-b \pm \sqrt{b^2-4ac} \over 2a}
$ equation

But this is not:

Inline $
x = {-b \pm \sqrt{b^2-4ac} \over 2a}$ equation

And neither of the above work with GitLab snippets.

Maybe you can find a spec somewhere, or test against other implementations (Obsidian, Typora, VS Code, etc.). Think about where the content (not just your content) is likely to originate.

But I get your point... a single newline in markdown does not signify the end of a paragraph.

---

GitHub gist example: https://gist.github.com/jmooring/f649aae89a2047e44541de2e3001fb0b

GitLab snippet example: https://gitlab.com/-/snippets/3637801

[jmooring]

Both "split" examples above work fine with the VS Code markdown preview, so maybe it's OK. My concern is false positives, which is why a spec would be great.

Both "split" examples also work with both KaTeX and MathJax, so I think you're right.

[j2kun]

My context is all coming from uses of MathJAX, KaTeX, and others in places like mathoverflow.com, math.stackexchange.com, and in normal LaTeX documents, where splitting mathmode across single-line breaks is always accepted (and double-line breaks are not). They also support using "block" mathmode in a paragraph, like

Hello I am $$x$$ how are you

And this would render the $$x$$ as its own offset equation, splitting the context line into two paragraphs.

I'm not aware of any standard spec, except LaTeX itself as a reference implementation. My plan is to test against KaTeX or MathJAX as a reference implementation.

[jmooring]

My plan is to test against KaTeX or MathJAX as a reference implementation.

Sounds good. I've added and organized test cases to the repo/branch mentioned above:

git clone --single-branch -b hugo-github-issue-10894 https://github.com/jmooring/hugo-testing hugo-github-issue-10894
cd hugo-github-issue-10894
hugo server

[j2kun]

I started implementing it, then got confused that the following tests are passing without any extension:

https://github.com/j2kun/hugo-goldmark-extensions/blob/main/passthrough/passthrough_test.go

Any idea why that might be? Do I need to configure the goldmark parser a certain way?

[jmooring]

You need to test with LaTeX that is mangled when the markdown is converted to HTML. Please look at these test cases:

git clone --single-branch -b hugo-github-issue-10894 https://github.com/jmooring/hugo-testing hugo-github-issue-10894
cd hugo-github-issue-10894
hugo server

Use the CommonMark demo to run quick tests.

The example that you've used in your tests is not modified when processed as markdown:
https://spec.commonmark.org/dingus/?text=An%20equation%3A%20%24x_1%20%3D%20y_1%24.%20Amazing

But this one is mangled:
https://spec.commonmark.org/dingus/?text=Inline%20%24a%5E*%3Dx-b%5E*%24%20equation

For your reading pleasure:
https://spec.commonmark.org/0.30/#emphasis-and-strong-emphasis