
Show HN: TeXMe Demo – Self-Rendering Markdown and LaTeX Documents - susam
https://opendocs.github.io/texme/examples/demo.html
======
oefrha
Pretty nice, although these days if when I need Markdown + LaTeX, most often I
just create an .ipynb, put it on GitHub (which could render Jupyter notebooks,
including LaTeX-splintered Markdown, since a while ago) and call it a day.

Btw, VSCode added native support for Jupyter notebooks recently.

~~~
wodenokoto
There’s been some form of notebook support in VSCode for a while, but nothing
that I liked enough to start using vscode over a notebook server. But I’d love
to be able to double click a .ipynb file and start editing and exploring.

Can you link the the recent support you talk about so I can compare it to what
I’ve already tried in vscode?

~~~
thegginthesky
[https://code.visualstudio.com/docs/python/jupyter-
support](https://code.visualstudio.com/docs/python/jupyter-support)

It is exactly as you mentioned, you click the notebook, it renders and opens a
Kernel on the background.

The plots have a default dark theme, but can be changed in the same way as if
it was inside a normal Jupyter instance.

It's pretty convenient, but a bit buggy still for larger notebooks (I have to
constantly save or some actions cause the cells to rollback in time).

~~~
oefrha
Yeah, I noticed that down arrow from the end of a markdown cell would leave
the cell and lose typed content. Fortunately I use Emacs keybindings (C-f,
C-b, C-p, C-n) to navigate for the most part.

------
doersino
Markdeep [1] does something very similar.

(Disclaimer: Not my project, but I've developed several Markdeep-adjacent
tools [2][3].)

[1]: [https://casual-effects.com/markdeep/](https://casual-
effects.com/markdeep/)

[2]: [https://github.com/doersino/markdeep-
slides](https://github.com/doersino/markdeep-slides)

[3]: [https://github.com/doersino/markdeep-diagram-drafting-
board](https://github.com/doersino/markdeep-diagram-drafting-board)

~~~
dteiml
This looks cool, even cooler than TexMe! Was going to start writing a Project
brief today, looks like I'm using Markdeep!

~~~
susam
Markdeep is a great project and supports a lot of impressive features. TeXMe
on the other hand takes a minimalist approach.

There are some fundamental differences between the two tools. For example, in
Markdeep, the user input goes into the <body> element whereas in TeXMe the
user input goes into the <textarea> element. The choice of <textarea> element
was made in TeXMe to make Markdown rendering more robust. Copy-pasting a valid
Markdown code into Markdeep may not always render correctly without further
editing. By the way, TeXMe also supports content in <body> as an optional
feature.

Further, Markdeep does not care about conforming to the CommonMark spec
whereas TeXMe does. If you care about CommonMark spec, TeXMe is a good choice.
However, if you need additional features like tables, diagrams, etc., Markdeep
is a good choice.

For a detailed comparison of the two tools, please see this thread:
[https://news.ycombinator.com/item?id=18314175](https://news.ycombinator.com/item?id=18314175).

------
foxes
I prefer katex [0] over mathjax these days. Seems to render a lot faster. I
wonder how this compares to Pandoc in terms of features. I really would like a
complete solution to take .tex files (theorems, references, figures) and turn
it into a html page, instead of a pdf. Pandoc is not quite there for me
(theorem environments!).

The main issue is that things like LaTeX theorem environments don't translate
exactly markdown (plus the theorem numbering/referencing), but there should be
some choice of convention. Seems like there was a focus on features that map
directly between different formats.

[0] [https://katex.org/](https://katex.org/)

~~~
Foivos
Have you tried Jupyter notebooks? I do not know if they handle references, but
it does the rest you want. The markdown cella support latex math and you can
include figures or even videos.

~~~
lrem
Isn't the TeX support in Jupyter based on MathJax?

~~~
Foivos
Yes.

[https://jupyter-
notebook.readthedocs.io/en/stable/examples/N...](https://jupyter-
notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html#LaTeX-
equations)

------
fastball
I'm not sure I understand what "self-rendering" means in this context? You
have some javascript that is taking markdown and spitting out HTML, right?

How is that different from any of the existing JS libs? The fact that it is
one line of code vs. a couple extra?

~~~
rambojazz
Probably because it's supposed to be "introspective", in the sense that you
just add a single HTML line to your otherwise usual markdown/tex files, and
the javascript recognizes this patterns ie. it ignores the <script> tag and
renders everything else.

------
bachmeier
This project is awesome, but by relying on Commonmark, you can't use this
together with code blocks containing $ (meaning it doesn't work for languages
like PHP and R). It's unfortunate that the Commonmark creators ignored
requests to handle cases like this.

~~~
oefrha
> It's unfortunate that the Commonmark creators ignored requests to handle
> cases like this.

What’s your proposed solution?

FWIW the main goal of CommonMark is to fix the ambiguity of Markdown.pl and
provide a common subset of features for all parsers to target, instead of
trying to include everyone’s pet feature.

~~~
bachmeier
> provide a common subset of features for all parsers to target, instead of
> trying to include everyone’s pet feature

I'm aware. Equations aren't exactly a "pet feature" though, unless things like
code blocks are also pet features.

There's an easy solution - have syntax that turns off parsing (a nowiki type
syntax).

Commonmark accomplishes very little if it can't be used to produce the
documents people are creating. If you want to add equations, you need an
extension. And if you use two extensions, you need to make sure they interact
correctly. And you have to be sure that all the extensions that might possibly
be used interact nicely together. At that point, you have your own version of
markdown, and you need to preprocess all your commonmark documents.

But yeah, it's nice that all commonmark implementations use the same syntax
for bold and italics. Unfortunately writing involves a lot more than that.

~~~
oefrha
> There's an easy solution - have syntax that turns off parsing (a nowiki type
> syntax).

Okay, that's fair, but CommonMark standardized de facto standards -- it was
born as Standard Markdown after all -- and AFAIK there's no de facto standard
here, so it would be pretty dangerous for jgm to pull something out of thin
air. I can see why there's reluctance here.

(IIRC fenced code blocks were pretty widespread before CommonMark, and even if
not, being part of GFM would almost make it a de facto standard. Note that
CommonMark was a joint effort among GitHub, Stack Exchange, Reddit, etc.; SE's
<!-- lang --> solution was atrocious, so GFM fenced code block was an obvious
win.)

Also, code blocks with language specification is apparently of way higher
importance to programmers than typeset math, so comparing the two isn't that
useful. (I say this as a physicist who breathe typeset math.)

Now, going back to

> you can't use this together with code blocks containing $ (meaning it
> doesn't work for languages like PHP and R).

Why do you need to typeset math _within code blocks or code spans_? Code
blocks and code spans are verbatim by definition. Interpret $ inside code
blocks and code spans as verbatim; interpret $ outside as LaTeX delimiters.
Problem solved. Maybe I'm missing something.

~~~
bachmeier
> Why do you need to typeset math within code blocks or code spans?

The problem is that commonmark doesn't recognize math at all. If you want to
use texme, you can't have code blocks that containing $. For it to work
properly, you'd need a preprocessor to parse the whole file, convert equations
in the text as needed but ignore text in code, output to a format that doesn't
cause problems with commonmark (for instance, protecting underscores outside
code blocks). At that point you are way beyond just "using commonmark". It's
simply not suited for even moderately complicated documents.

------
manbash
From a look at the github, there is a sudden "surge" or commits, likely to
prepare to present it to hackernews. But overall this github doesn't seem to
be maintained and users issues are sitting there unanswered.

[https://github.com/susam/texme/commits/master](https://github.com/susam/texme/commits/master)

~~~
susam
You are right. When I was about to share the project demo page today, I
realized that it should have a link to the project README, so that visitors
can read how to use this project. That's when I pushed a commit today. So
while I was at it, it made sense to do a few other minor cleanups.

The tool, as is, works for me and my friends. I don't intend to make any major
changes to this tool except for occasional bug fixes, so the number of commits
is going to be less in future.

I know there are a few outstanding bugs. I have a full-time job and I am
contributing to a few other open source projects too, so I don't have a lot of
spare time to investigate and fix these issues right now but I may get to it
later.

If there are others who might want to help the project by investigating the
bugs and/or fixing them, they are very welcome. For any fixes merged to the
project, I will be grateful to the contributors and as a token of gratitude, I
will mention their names in the README and thank them.

~~~
n_ary
> If there are others who might want to help the project by investigating the
> bugs and/or fixing them, they are very welcome. For any fixes merged to the
> project, I will be grateful to the contributors and as a token of gratitude,
> I will mention their names in the README and thank them.

Your claim doesn't match your intent really. Some of your repos have long(many
months) old issues with zero interaction from you yet I see activity in commit
history.

For small projects like yours, there might be first-time contributors who look
up to an author. If you don't interact, they'll get demotivated. If you don't
want to interact, leave a comment on your README that "hey am super busy, send
a PR with proper tests and may be I'll look when am free, no promises!". :) A
little kindness goes a long way.

~~~
susam
Thank you for the feedback. I usually do not prefer commenting on an issue
when I know I cannot add something new about the issue. At the same time, I
understand your point about the need to interact. I will keep it in mind for
future. I will also begin responding to the old issues in the next few days.
:-)

------
tomrod
FINALLY!

Thank you for this!

Edit: If any @Amazon Kindle devs read this, can you please reskin your
technical texts to adopt this?

------
yig
Previous discussion (2018-10):
[https://news.ycombinator.com/item?id=18307747](https://news.ycombinator.com/item?id=18307747)

------
ncmncm
This is brilliant.

All we need now is a way for it to fall back to pre-rendered static html for
cases where there is no JS, and to be indexed.

~~~
rcthompson
Wouldn't that entirely defeat the purpose? If you're already pre-generating
the HTML anyway, it's a waste not to just always serve it, making the self-
rendering part redundant.

~~~
ncmncm
Bingo. But it is still brilliant.

------
skywal_l
(Shameless self promotion) I created something equivalent that has an editor
too:
[http://mathdown.novidee.com/14db95afe202f4c1adfc3214aa57af01](http://mathdown.novidee.com/14db95afe202f4c1adfc3214aa57af01)

------
bhl
Given that it’s parsing from a textarea, can TeXMe be used as an editor? I
think some contenteditable editors have the rendering from markdown as well.

~~~
susam
Do you mean something like this:
[https://opendocs.github.io/texme/examples/interactive-
demo.h...](https://opendocs.github.io/texme/examples/interactive-demo.html)?
TeXMe can be used in this manner but not out of the box. If you see the source
code of this interactive demo page, it uses the texme.render() function call
from the TeXMe API to take input from the textarea element and render it in a
div element.

Providing an interactive editor was not the goal of this project. The goal of
this project was to write a text file using a mix of LaTeX and Markdown (while
conforming to CommonMark specification as much as possible) and then share
this file with my friends in such a way that they can render it easily by just
opening it in a web browser. As a result, it completely replaces the textarea
element with the rendered HTML.

If someone wants to take this project and create an interactive editor with
it, please feel free to fork this project and do so. If you face any problems,
please let me know by filing issues on the GitHub project:
[https://github.com/susam/texme](https://github.com/susam/texme).

------
hyperpallium
Would this work offline, by <script> referring to your local copy of
texme.min.js
[https://github.com/susam/texme/blob/master/texme.min.js](https://github.com/susam/texme/blob/master/texme.min.js)
?

Or is there much more to it?

~~~
oefrha
Apparently TeXMe needs to load MathJax which in turn needs to load a bunch of
fonts, so no, that script alone won't work offline.

------
snicker7
Consider pre-rendering formulas instead of doing it client-side (KateX
supports this, dunno about MathJax). In my experience, rendering a lot of
equations on screen via MathJax can be quite taxing.

------
chabad360
As cool as this is, I just don't really see the use for this, when static site
generators like Hugo and Jekyll exist, and produce pages that will load
measurably faster...

------
smabie
I use org mode + pandoc to achieve the same thing. Jekyll than converts the
markdown to html and with a mathjax header, makes a really nice blogging
system.

------
enhdless
What are the pros and cons of rendering content like this?

~~~
kbr2000
Debatable, but it might

\+ save some network bandwidth in case of a sufficiently large/complex
document

\- burn some extra energy client-side in case of a sufficiently large/complex
document

\+ allow some kind of interactive manipulation/modification by the reader

------
jhoechtl
I would like this for Asciidoc which is the better Markdown

------
billconan
is this just latex math or the full latex?

------
alexmint
Rendering quality is really good. Looks just like PDF.

~~~
jimws
> Looks just like PDF.

It's better than PDF. Text in PDF is not reflowable. This demo is by virtue of
being HTML under the hood. Looks good even after resizing the browser.

I wish PDFs had a reflowable mode. What would it take to add such a mode to
the PDF spec without breaking backward compatibility?

PDF's fixed layout is a real problem when we try to convert PDF books
containing math to EPUB or MOBI with Calibre. It really messes up the
beautifully typeset math in the PDF during the conversion. What's a good
solution for this?

~~~
jahewson
> I wish PDFs had a reflowable mode. What would it take to add such a mode to
> the PDF spec without breaking backward compatibility?

PDF has everything including the kitchen sink. There’s a fairly esoteric
feature called “tagged PDFs” which contain extra markup commands within the
page description that map it to a logical structure and alternative textual
presentations (e.g. MathML). The problem is that nobody uses it as it’s
extremely hard to generate (most software which does text layout discards high
level semantic details fairly early on, making it hard to retrofit - pdfTeX
for example only recently started inserting space characters between words!).
Likewise PDF viewers don’t bother to support it.

Reflowing a tagged pdf is fairly easy... once you have the pdf, which of
course you don’t.

It’s a hard problem.

~~~
oefrha
I heard tagged PDF is one of the goals of LaTeX3, and LaTeX3 work has thus far
been available as packages on top of LaTeX2e, which means it should work on
LaTeX2e too. I’ve never tried it though.

~~~
adiM
ConTeXt supports tagged pdf out of the box

