In syntax def doc examples, show html output rendered as well

[uvtc]

It would help to quickly visualize and learn what a bit of djot markup does if the examples contained rendered html in addition to the raw html output.

[uvtc]

That is, in https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html.

[jgm]

Well, it's hard to put three things in columns; there's not really enough room for them to display nicely.

[uvtc]

Since some of the examples are wide things like tables or hr's, maybe the rendered html could be displayed underneath both, in its own row that spans the two cols? Could even have a different background color than the jdot and html blocks/cells.

[jgm]

I could try just having the rendered HTML.
Or to be really fancy, show the rendered HTML but allow clicking something to show the HTML.

[uvtc]

I think it's most valuable to be able to look at the jdot and the rendered html at the same time.

It could also be valuable to see the raw html sometimes.

Maybe optimal would be jdot markup and rendered html side-by-side, and then a click-to-reveal the raw html if the reader wants to see it.

[wooorm]

I could try just having the rendered HTML.
Or to be really fancy, show the rendered HTML but allow clicking something to show the HTML.

Maybe something like this? (https://esbuild.github.io/getting-started/#bundling-for-the-browser)

---

I think it's most valuable to be able to look at the jdot and the rendered html at the same time.

I disagree. I find it more important to see what the function of jdot is: it’s input, and its output. Not how browsers render such output.

[uvtc]

Hm. Good point, @wooorm . Maybe it depends upon who the reader is. I suspect:

• if the reader just quickly wants to see which syntax yields what output, I think that "djot --> rendered html" will be most useful to them.
• if the reader wants a concise reference of djot behavior, then "djot --> raw html" may be most useful to them.

Anyhow though, regardless: the syntax reference in question happens to be using html for its output examples. The djot readme says djot is not HTML-centric. So, for users who are not targetting html as their output format (and who may not even know much html at all), it would help them to see some kind of rendered output.

Incidentally, I found this markdown doc that goes with three cols for the smaller examples, but then reverts to the sequential style when it gets to blockquotes and images.

[wooorm]

if the reader just quickly wants to see which syntax yields what output

This could partially also be solved with a cheatsheet-like page, something along the lines of https://commonmark.org/help/. The markdown doc you later link also is such a page.

[uvtc]

I think @wooorm 's idea of a separate cheatsheet is a great idea.

@jgm , I'm ok with closing this issue, but am leaving it open in case you are still thinking about adding reveal buttons to the syntax reference.

[waldyrious]

Note: even though there's now a cheatsheet (thanks for adding it in #39, @uvtc!), I still think it would be worth showing the rendered HTML output in the full syntax document.