
Show HN: TeXMe – Self-Rendering Markdown and LaTeX Documents - susam
https://github.com/susam/texme
======
andridk
As someone who has written a few of LaTeX documents over the years, I'd like
to point out that rendering TeX math does not constitute a TeX document at
all.

What LaTeX truly shines at, is typography. Yet a bunch of people seem to think
that it's only a way to write math.

This is an interesting project. It just bums me out because I thought it was a
TeX distribution for the web. I'd remove "TeX" from the name to avoid
confusion.

~~~
paraditedc
> _What LaTeX truly shines at, is typography._

I respectfully disagree. I think people use LaTeX to write scientific
documents because there is no better alternatives, not because LaTeX is good.

I find the typesetting system in LaTeX is extremely verbose and over-
complicated, as compared to something like HTML+CSS or Markdown.

If someone comes up with a good enough typesetting system with some
inspiration from Markdown, HTML and CSS, LaTeX will lose its popularity. HTML
and CSS are more expressive than LaTeX, so it should be theoretically
possible.

One possible explanation for the lack of better alternatives is that the
people who really need the alternatives and people who are capable of coming
up with better alternatives are somewhat mutually exclusive. Former is more
research-heavily and latter is more coding and user experience heavy.

~~~
kderbyma
Latex is a fully Turing complete language as well as a typesetter. Only with
JavaScript can you compare them.

~~~
danShumway
I mean, CSS/HTML is _technically_ a Turing complete language given enough
caveats[0]. ;)

But I'm obviously just being a pedantic jerk when I say that. I get what
you're getting at and you're not wrong. The real question to ask is, "is a
programming language a good place to put a typesetter?"

Making things more powerful doesn't _always_ make them better, if that extra
power forces you to introduce extra complexity.

[0]: [https://my-codeworks.com/blog/2015/css3-proven-to-be-
turing-...](https://my-codeworks.com/blog/2015/css3-proven-to-be-turing-
complete)

~~~
taeric
Why is that the real question to ask? The dogmatic separation of view and
control is probably among the chief reasons of code bloat and bad decisions
I've ever been close to.

~~~
danShumway
An example of good separation of model/view/control is Markdown.

Markdown is ubiquitous because it's easy to learn and does one thing well.
It's a very Unix-y idea. Markdown is a document markup language, not a Model-
View-Controller framework. It's not trying to be the front end for your SPA,
it's trying to allow you to type Reddit comments and blog posts.

That comes with advantages, the big one being that here's the entire
documentation you need to look at if you want to start using Markdown[0] and
here's _one section_ of LaTeX's documentation[1]. I could have an entire
office (programmers and non-programmers) using Markdown in about a week to a
month, I couldn't do the same with LaTeX.

Of course LaTeX is more powerful that Markdown. Markdown isn't really a tool
for typesetting tbh. But the point is that because extra functionality nearly
always comes at the cost of extra complexity, you always need to take a step
back and ask how important that extra functionality is. If someone says,
"Okay, but I really need to meta-program my blog post", even at that stage I'm
not sure that I push them towards LaTeX or its equivalents, because maybe it's
better at that point to just jump to a full featured language like Python or
Javascript.

That separation of concerns also means that I can have different people
handling different things. If my office is all writing Markdown, maybe I only
have one or two people who are handling the CSS for how it renders. Nobody
else in the office needs to know about the CSS side of things.

[0]:
[https://daringfireball.net/projects/markdown/syntax](https://daringfireball.net/projects/markdown/syntax)

[1]: [https://www.latex-
project.org/help/documentation/fntguide.pd...](https://www.latex-
project.org/help/documentation/fntguide.pdf)

~~~
taeric
And yet, I have grown to dislike markdown.

Markdown it's essentially ASCII art for simple documents. Nothing wrong with
that, but it is not seperation of concerns. Rather, it is simplicity of some
concerns.

And to make it hugely amusing, the rules in markdown for just content are not
much different than TeX.

~~~
danShumway
I think Markdown is a good argument for potentially being _too_ simple. It's
good for what it's meant for, but it stumbles for stuff like blog authoring.

I am somewhat happy with AsciiDoctor[0], although I honestly feel like
AsciiDoctor goes farther in the other direction than it needs to and ends up
overcomplicating itself. I spend more time reading the AsciiDoctor
documentation than I want to.

Would you be willing to expand more on what you mean about a separation of
concerns vs a simplicity of concerns? I was using the term in the sense that
Markdown not only doesn't embed logic, it also doesn't embed style. It's
literally just content, and you use other technologies to get at the other
parts.

In contrast, LaTeX embeds logic, style, and content. When I work with Markdown
I don't stop thinking about style -- I just use other tools for that. That
separation allows me to then give other people content access without asking
them to worry about CSS.

I guess I could see that it's a flat-out dropping of meta-programming from my
document generation (although Markdown is a very easy compilation target for
templates). But that just kind of gets back to my original point -- do you
really need to meta-program blog posts and books, given that it greatly
increases the complexity of LaTeX? Would it be better to have a simpler
version of LaTeX that got rid of that functionality and said, "I'm just gonna
do text layout _really_ well, and nothing else"?

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

~~~
taeric
"Simplicity" was a typo. I blame my phone. :(

I meant "simplification of concerns." Basically, if you simplify what concerns
the content author can have, it is easier to encode them. In the case of
markdown, you are very limited in what you can define.

And I am not at all against the ideas. I'm very partial to org-mode. For
example, I wrote
[http://taeric.github.io/Sudoku.html](http://taeric.github.io/Sudoku.html)
using an org-mode buffer. And I've been very happy with the markup it
supports. However, there is a lot of markup around some things it can do. And,
I've found that the constant churn as folks improve it has been tiring. I
think it has stabilized recently, which is good.

------
SagelyGuru
This is a godsend to anyone who just wants to publish markdown blogs (with
some maths) etc in the simplest possible way on a static website.

I know, the proper way is supposed to be to use Jekyll or Hugo or something
like that, to compile to raw html on the server side but this is much simpler
for the publisher. No configuration and compilation and updating on the server
involved.

I do not think that the user will notice or begrudge the few milliseconds of
processing in his browser. Especially if this could be converted to a WASM
module. Any takers?

~~~
bhl
Two different approaches: Jekyll is often top-down, start with a theme that
you like and make edits to the css and html files until you get something you
like. Downside is if you want to make major changes, you’ll have to understand
complex code you didn’t write yourself. The approach given by this post is
bottom-down; start with some basic css edits. Downside is you may spend enough
time customizing that using a Jekyll would have been better. ‍️

~~~
SagelyGuru
That is true. I have used Jekyll but having to study obscure settings files
and complex directory structures is not enjoyable when all you really want to
do is to get on with writing your blog.

------
garganzol
I'm very grateful you created this. It is going to be a tool #1 in my
workflow. The best thing I like is that the resulting document can be printed
or saved as a PDF file with web browser printing dialog.

Impressive. A sweet spot between HTML, Markdown and LaTeX.

------
arendtio
I think that is pretty cool.

The one thing I would wish for is a build tool where I could insert my CSS (or
a choose from available themes) and build my version of TeXMe (I have a CSS
file already which I use to convert Markdown files to PDF).

I mean, yes it is not that complicated, and I might just do it manually, but
for wider adoption, it would be cool to have themed versions which do not
clutter the Markdown files.

~~~
chrisweekly
Huh? How do you use CSS to convert MD to PDF?

~~~
arendtio
Well, not directly.

I have a script which converts Markdown to HTML (using Discount; referencing
my CSS file and highlight.js for syntax highlighting in code sections) and
starts a headless chromium which in turn converts the rendered HTML to a PDF
file.

~~~
chrisweekly
That sounds a lot more like it. :)

Care to share your script?

~~~
arendtio
[https://www.filedropper.com/markdown2pdf](https://www.filedropper.com/markdown2pdf)

    
    
      $ sha256sum markdown2pdf.zip 
      97b9df1091cb29e15b699fe1b87d0de20929abfe5357d9e4db920fb24a76406b  markdown2pdf.zip
    

It consists of multiple files (entry point is markdown2pdf.sh) and also
supports a flag '-w' to watch the markdown file so you can use an editor to
modify it while your PDF viewer (in my case okular) keeps updating the
changes.

I built it solely for my purpose, so it might not fit your needs (or taste).
;-)

Legal: I have no special requirements, so think of it as MIT license, but I
included some other files (everything in the directory 'Markdown-Styling'
except 'css/app.css' which is my CSS theme) which are available free of charge
somewhere on the internet but might have their own licenses and terms of use.

------
tdgunes
Can you explain how different TexMe is than Markdeep?

~~~
wahern
I'm curious, too, though I suspect the author either wasn't aware of Markdeep
or just wanted to scratch their own itch.

I use Markdeep for most Markdown content, including Github, as I like being
able to compose in my own editor, joe, but be able to quickly see the results
before committing without having to explicitly compile anything--just tab into
browser and refresh.

The "problem" with Markdeep is that it supports _so_ many different features
(including LaTeX math typesetting, but also ASCII diagram rendering) that it
can be difficult stick to a common subset supported by, e.g., Github.

~~~
susam
An important difference between Markdeep and TeXMe is that in Markdeep, the
Markdown + LaTeX code goes in the <body> element itself.

But in TeXMe, the Markdown + LaTeX code goes in a <textarea> element. This
difference, in my opinion, leads to more robust parsing of the input. TeXMe
handles some cases fine where Markdeep breaks. For example, this Markdown code
breaks in Markdeep:

    
    
      Here is a fenced code block that breaks in Markdeep:
    
      ```
      print("unusual <string")
      ```
    
      <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style>
      <script src="markdeep.min.js"></script>
      <script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
      <script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
    

The `<string` in the above code is interpreted as the opening of an HTML start
tag by the browser. So what looks like a fragment of Python code to a human
ends up being parsed as an HTML tag by the browser that looks like:

    
    
      <string") ```="" <script="" src="markdeep.min.js">
    

Once the browser has mangled the input like this, there is no way for Markdeep
to retrieve the original input entered by the user.

Markdeep's answer to this problem is to use HTML entity `&gt;` instead of `<`.
But that disrupts the natural flow of taking notes in a text file where we
might want to paste verbatim code.

TeXMe's answer to this problem is to put the input inside a <textarea>
element. So the same example works fine in TeXMe and MdMe:

    
    
      <script src="https://cdn.jsdelivr.net/npm/texme"></script><textarea>
    
      Here is a fenced code block that breaks in Markdeep:
    
      ```
      print("unusual <string")
      ```
    

The user input is within <textarea> element, so the entire input can be
retrieved verbatim and rendered correctly. This is precisely the reason why I
wrote TeXMe. I was writing a lot of documents related to neural networks and I
needed to paste code examples without having to bother about substituting
special characters with their HTML entities.

The other minor difference I see is that Markdeep does not conform to
CommonMark. It has several restrictions. For example, Markdeep does not
support indented code blocks, two trailling spaces for hard linebreak, intra-
word emphasis with asterisk, setext headings with one/two minus/equals
characters as underline, and single line blockquote. TeXMe is not opinionated
about CommonMark. It just hides math content, invokes commonmark.js to render
CommonMark, then unhides math, and invokes MathJax to render math. MdMe is
even simpler--it just invokes the commonmark.js processor on load. For
example, the following code, although valid Markdown (CommonMark), does not do
what we normally expect:

    
    
      H1
      ==
    
      Intra*word* emphasis.
    
      > What I cannot create, I do not understand. -- Richard P. Feynman
    
          print("hello")
    
      Line  
      break
    
      <!-- Markdeep: --><style class="fallback">body{visibility:hidden;white-space:pre;font-family:monospace}</style>
      <script src="markdeep.min.js"></script>
      <script src="https://casual-effects.com/markdeep/latest/markdeep.min.js"></script>
      <script>window.alreadyProcessedMarkdeep||(document.body.style.visibility="visible")</script>
    

It works fine with TeXMe or MdMe:

    
    
      <script src="https://cdn.jsdelivr.net/npm/texme"></script><textarea>
    
      H1
      ==
    
      Intra*word* emphasis.
    
      > What I cannot create, I do not understand. -- Richard P. Feynman
    
          print("hello")
    
      Line  
      break
    

TeXMe or MdMe is a good choice if you care about conformance to CommonMark and
pasting code verbatim in your files but do not need the additional features
that Markdeep provides. Markdeep has a very impressive feature set that
includes task lists, definition lists, tables, diagrams, syntax highlighting,
etc. This makes writing many different types of documents possible in
Markdeep.

TeXMe and MdMe, on the other hand, take a minimalist approach and focus only
on getting the CommonMark and LaTeX (MathJax) rendering right by keeping
CommonMark.js and MathJax out of each other's way.

By the way, to use MdMe instead of TeXMe, just replace "texme" in the CDN URL
with "mdme".

~~~
susam
This is an update to the above comment.

TeXMe and MdMe (stripped down fork of TeXMe) now support Markdeep style of
putting the content directly in the <body> element (i.e., without a <textarea>
element) and then putting the <script> tag to load TeXMe/MdMe at the end of
content.

But this method has the same caveats that Markdeep has, i.e., an HTML syntax
error in the content can lead to broken rendering. Therefore, I recommend
using TeXMe's original method of putting the content in textarea for more
robust parsing and rendering.

For further details, please see:

* [https://github.com/susam/texme#content-in-textarea](https://github.com/susam/texme#content-in-textarea) (TexMe's original method of writing content in textarea that leads to robust parsing and rendering).

* [https://github.com/susam/texme#content-in-body](https://github.com/susam/texme#content-in-body) (The new method of writing content in body that makes the content look neat but has some caveats. See the "Caveats" subsection in this section for details.)

------
blattimwind
> The rendered document demonstrates two interesting features of TeXMe:

It also demonstrates documents created this way require code from two
different third-party origins to work at all.

------
andrepd
Wouldn't it make more sense to compile the markdown and serve the result,
rather than having the user render it client-side? Seems very inefficient.

~~~
susam
Pandoc, commonmark.js, and many other tools and libraries can already do that.
This project is not trying to address that use case. Instead, this project is
attempting to make a Markdown + LaTeX (MathJax) file render itself with
minimal additional HTML.

~~~
akavel
A cool advantage is that one should be able to just write the file by hand in
any Markdown (or text) editor on any random PC, and then with this fairly easy
to remember one-liner insta-convert it to a pretty document for viewing in a
browser. I'd go this far as positing that this could become somewhat of a
"standard preamble" for .md files... or at least that it could be an
interesting thought experiment to imagine that :)

Well done!

~~~
wahern
The browser still needs to recognize it as text/html. I use Markdeep
([https://casual-effects.com/markdeep/](https://casual-effects.com/markdeep/))
and to get Chrome to auto-render locally I need to hard link to a name with a
.html extension.

Also, it doesn't technically need to be a preamble. Markdeep works by
appending similar code to the end, which is much more innocuous when viewing
the file outside a browser or when its rendered by other software (e.g. on
Github).

~~~
susam
> Markdeep works by appending similar code to the end, which is much more
> innocuous when viewing the file outside a browser or when its rendered by
> other software (e.g. on Github).

Thank you for highlighting this feature of Markdeep. I have now added this
feature in TeXMe and MdMe too. We can now put the `<script>` tag to load TeXMe
or MdMe at the end of content. Here is an example:

    
    
      # Euler's Identity
    
      In mathematics, **Euler's identity** is the equality
      $$ e^{i \pi} + 1 = 0. $$
    
      <script src="https://cdn.jsdelivr.net/npm/texme"></script>
    

However, like I have explained in another comment[1], this method of writing
content requires the content to not have any HTML syntax errors, otherwise the
output would be mangled. Markdeep has this limitation too. There is a
'Caveats' section[2] in the README now that discusses this in detail.

The original method of writing content with a single line of HTML code at the
beginning of the content does not have this limitation. But if the HTML code
in the beginning feels distracting, we can now put the `<script>` tag in the
end too.

[1]:
[https://news.ycombinator.com/item?id=18314175](https://news.ycombinator.com/item?id=18314175)

[2]:
[https://github.com/susam/texme#caveats](https://github.com/susam/texme#caveats)

------
platform
Is there a chance that the HTML TexMe produces could be rendered via React-
Native Text control [1] ?

[1][https://facebook.github.io/react-
native/docs/text](https://facebook.github.io/react-native/docs/text)

------
mxstbr
Does anybody know if a similar thing exists that renders out markdown without
LaTeX?

That'd be a neat way to quickly create documentation websites for open source
projects!

~~~
susam
Yes, TeXMe does it. Here is a minimal example:

    
    
        <!DOCTYPE html>
        <script>window.texme = { useMathJax: false, protectMath: false }</script>
        <script src="https://cdn.jsdelivr.net/npm/texme"></script><textarea>
    
        ### Atomic Theory
    
        Atomic theory is a scientific theory of the nature of matter, which
        states that matter is composed of discrete units called atoms. It began
        as a philosophical concept in ancient Greece and entered the scientific
        mainstream in the early 19th century when discoveries in the field of
        chemistry showed that matter did indeed behave as if it were made up of
        atoms.
    

Right now, it requires a few more lines of HTML code to disable MathJax
related processing. I am planning to add a simpler mechanism later, so that
something like merely appending "?markme" to the TeXMe URL in the <script> tag
is enough to set it to Markdown-only mode. If anyone has a better idea
regarding this, please let me know or send a pull request.

~~~
tomer_shalev
Doesn't this solution also loads all the code for rendering math? Maybe a
separate, smaller, library would be a better solution.

~~~
susam
Thanks to your suggestion, I have now created a separate, smaller, library
named MdMe: [https://github.com/susam/mdme](https://github.com/susam/mdme).

This is a stripped down fork of TeXMe that does not contain any code for
MathJax related processing.

Here is a minimal example:

    
    
        <!DOCTYPE html><script src="https://cdn.jsdelivr.net/npm/mdme@0.1.0"></script><textarea>
    
        # Atomic Theory
    
        **Atomic theory** is a scientific theory of the nature of matter, which
        states that matter is composed of discrete units called *atoms*.
    

This is absolutely fresh--published only a few minutes ago. If you find any
issues, please report it.

I hope you like this.

~~~
SagelyGuru
I tried and it does not work with the custom formatting. Could we have that
too?

~~~
susam
The example[1] I have linked to under the section titled "Styles" in README
seems to show that custom style is working. Or do you mean something else by
"custom format"?

If you can provide a reproducible example of the issue, it would help me to
understand the issue and fix it. I suggest filing a new issue with the
details.

[1]: [https://opendocs.github.io/mdme/examples/e04-style-
custom.ht...](https://opendocs.github.io/mdme/examples/e04-style-custom.html)

~~~
SagelyGuru
What I have done is to take you at your word that even valid html does not
need <body></body> and combined your examples of "valid html5" and
"style=none" but it then failed to apply my own style to <body>.

I am kind of surprised that the styling does work in your minimalist html
(style=none) example because there the <body> is missing too and yet the style
is applied to it.

You might wish to take this pitfall into account in your exposition, probably
by putting <head> and <body> sections into your "valid html5" example
nonetheless.

Though I acknowledge that, strictly speaking, you had done nothing wrong in
your individual examples.

~~~
susam
Thank you for your reply.

The <body> element's start and end tags can indeed be omitted under certain
conditions (which are being met in the "Valid HTML5" example). Here is the
actual specification quoted from
[https://www.w3.org/TR/html52/syntax.html#optional-
tags](https://www.w3.org/TR/html52/syntax.html#optional-tags):

"A body element's start tag may be omitted if the element is empty, or if the
first thing inside the body element is not a space character or a comment,
except if the first thing inside the body element is a meta, link, script,
style, or template element."

Then in "Example 6", it provides the following as an example of a valid HTML5
document:

    
    
        <!DOCTYPE HTML>
        <title>Hello</title>
        <p>Welcome to this example.</p>
    

Now coming back to your issue, perhaps the selectors in your style do not
match the actual elements that TeXMe is setting in the page? I am just
guessing here because I need the actual code to be able to nail down the cause
of the issue.

If you can share the complete code you have either here or at
[https://github.com/susam/texme/issues/new](https://github.com/susam/texme/issues/new),
it would really help in determining the cause of the issue.

~~~
SagelyGuru
Bug solved, sorry, ignore all my previous comments. I had done a stupid thing:
I forgot to change the command window.texme = { style:'none'} to window.mdme =
{ style:'none'} when I started using mdme. That is why it was not applying the
correct styling.

~~~
susam
Thank you for sharing the cause of the issue. Good to know that the styling is
working as expected after setting window.mdme = { style: 'none'}.

------
luckylittle
There are already tools doing similar thing:
[https://www.sharelatex.com/](https://www.sharelatex.com/)
[https://latexbase.com](https://latexbase.com)
[https://papeeria.com/](https://papeeria.com/)

~~~
foo101
None of the tools you mention does anything similar to the tool shared in this
post. What similarity do you find apart from the obvious and peripheral
similarity that they are all rendering latex?

The first and third tools require you to sign up. How exactly do you create a
distributable Markdown file there that can be read both in editor as text and
viewed as HTML in browser? The second link does not recognize Markdown.

------
zzo38computer
I use Plain TeX for typesetting, and it is good. (I don't use LaTeX. I think
Plain TeX is better. And, for making fonts, METAFONT is better.) But to render
TeX documents you will need to implement TeX. (You could, however, implement a
TeX macro package that you can then use the same input for multiple kind of
output.)

------
Too
This project is just evidence that markdown rendering should be built into the
browser.

~~~
c-smile
But why?

Isn't it better to use something like my [https://html-
notepad.com](https://html-notepad.com) where you can just create/edit your
document in WYSIWYG and use Markdown as one of input options? (Markdown is
coming there).

I think that this is the best of two worlds.

~~~
platform
there are many online services that allow users to 'edit' their content
snippets (eg blog posts/etc). So these users are not expected author their
content offline.

In those cases, having an online editor and an rendering engine that supports
something like markdown, is beneficial.

------
ajnin
The example is incorrect, it should be e^{i \pi} + 1 = 0

~~~
susam
Whoops! That was incorrect indeed. A very unfortunate typo because it happens
to be a favourite equation of many people, including me.

Thank you for reporting this. I have fixed it now.

~~~
ajnin
It's probably my favorite as well, I remember learning it in school, the way
it brings together e, i and pi, which seemed to live in separate worlds until
then, amazed me, it was like discovering the keystone of math.

