search

carpentries / lesson-example

Example lesson using The Carpentries lesson template.
https://carpentries.github.io/lesson-example/
Other
64 stars 173 forks source link

Document katex math support #345

Closed tobyhodges closed 1 year ago

tobyhodges commented 3 years ago

The template now supports rendering of equations in LaTeX syntax and this should be documented in the Lesson Example. I believe the appropriate place would be 04-formatting.md.

CunliangGeng commented 2 years ago

The equations in example lesson are not properly rendered: image

zkamvar commented 2 years ago

Thank you @CunliangGeng for bringing this up!

In short, I do not think we will be fixing this issue for three reasons:

  1. In May, we will be transitioning to use The Carpentries Workbench
  2. Support for math rendering in episodes was added in 2021, but it has an unfortunate history that reflects a common pattern in open source: a feature is requested and partially implemented, but there was no follow-through to fix a pretty big flaw (see https://github.com/carpentries-incubator/metagenomics/issues/31#issuecomment-1125509310)
  3. We have limited capacity on The Carpentries staff. The process for updating lessons with the styles repository is difficult and that for updating incubator lessons is even more difficult.

One potential solution for you would be to copy this javascript.html file into your _includes/ folder, which would enable mathjax and fonts for your repo (note: this is what the original author of the math support opted to do).

tobyhodges commented 2 years ago

@zkamvar I wonder if we should remove the section from the Lesson Example documentation? It's a relatively quick "fix" that will prevent people from running into the same problem again between now and May.

GuillermoFidalgo commented 1 year ago

I agree with @tobyhodges and think we should document a solution like @zkamvar has listed above. That solution did not seem to fix it for me.

Maybe just mention that adding the following at the top of the .md files where math is needed should be enough.

<script type="text/javascript" async
src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-MML-AM_CHTML">
</script>