Proper way to add "alert"/"note"/"hint"/"warning"/... boxes?

[mgeier]

I apologize if this has been discussed before, but I didn't find anything about it in the issues ...

I often see colored boxes in Markdown cells, e.g. in docs/source/examples/Notebook/Notebook Basics.ipynb (rendered by Github/nbviewer).

Those are typically created with raw HTML <div>s like this:

<div class="alert alert-success">
Blah blah blah
</div>

This looks nice and all, but

1. It's kinda tedious to type
2. The colored boxes (but not their content) get lost in translation to LaTeX

Is there a better way to create those boxes?

[Carreau]

Is there a better way to create those boxes?

Hum, not as far as I am aware, we would have to have some king of markdown role like in sphinx/rst.
Hope the common mark folks come up with a syntax for this soon !

[jankatins]

As a workaround you could use a python object which implements _repr_html_ and _repr_latex_:

class Alert():
    def __init__(self, text):
        self.text = text
    def _repr_html_():
        return '<div class="...">text</div>'
    def _repr_latex_():
        return '...'

This would return both html and latex and would therefore be visible in both. But now you need to remove the cell itself (not sure how that works...)

[mgeier]

@Carreau Thanks, it's good to know that I didn't overlook anything.
@JanSchulz Thanks, but no thanks. I'm looking for a proper solution, not for a work-around.

@Carreau wrote:

Hope the common mark folks come up with a syntax for this soon !

I don't think this will happen anytime soon. This was discussed over and over for years, but nothing was added to CommonMark. A few proposals are have been collected in the CommonMark Wiki under "Directives".

What about implementing one of them in The Notebook as a Markdown extension?

Could someone please point me to the code where Markdown cells are parsed?
Probably there is already an extension available for whatever JavaScript library is used for that?

Here are a few more links:

• admonition support for Python-Markdown: https://pythonhosted.org/Markdown/extensions/admonition.html
• proposed admonition support in pandoc: Add Markdown Admonition Support jgm/pandoc#2610

[Carreau]

What about implementing one of them in The Notebook as a Markdown extension?

Well, I doubt we have enough bandwidth to implement our own markdown parser/renderer, in js and then in nbconvert, and then in all the other software that support the notebook format.

Could someone please point me to the code where Markdown cells are parsed?

notebook/static/notebook/js/textcell.js MarkdownCell.prototype.render ~ Line 370

[takluyver]

Additionally, if everyone gives up on the standard and does their own versions, we end up in the same kind of mess that led to the creation of CommonMark in the first place. So I think we should say no to ad-hoc extensions, and encourage people who don't like that to go and improve CommonMark.

[jankatins]

Just putting in a few good words for a pandoc based notebook/nbconvert: pandoc because that's used on the R side with knitr/RMarkdown and because it is (next to github) the kind of "extended standard". knitr/RMarkdown currently (and more so in the future if e.g. better tables are added to pandoc or the above admonition support) have an advantage on the things they can express vs what can be expressed in the notebook md cells. nbconvert can probably easily switch to pandoc, but the browser would need a md2html webservice (e.g. using pypandoc). Whether it would be worth it? The tables feature might be a great addition, as it would mean that more richly styled html tables could be translated into pdfs.

@mgeier If you don't need interactivity, just html and latex/PDF support (and after pandoc gets everything you want), you could try to write admonitions into md cells (or raw cells?), ignore the error in the notebook and then convert the ipymd file to md using nbconvert and then the md file to whatever pandoc supports via pandoc.Or use python-markdown now, if that has a commandline util which works like pandoc.

[mgeier]

@Carreau

I'm not talking about implementing a Markdown parser (or several of them), I'm talking about an extension (or several of them).

Thanks for the pointer, here's a link.
Apparently, there is already some pre-processing being done before marked is used for the actual conversion.

In the next few days (or weeks) I'll have a closer look how my proposed extension could be added there.

@takluyver

The goal of CommonMark, as far as I understand, is to have an unambiguous spec for the most "common" Markdown features. CommonMark allows, probably even encourages, extensions.

There are many proposed extensions (same link as I gave above), most of them will never be part of CommonMark.
In the discussions linked from the wiki page, the CommonMark authors even encourage people to create extensions.
And since extensions like the one i'm suggesting have been discussed for years and not been added to CommonMark, leads me to predict that it ain't gonna happen.

Fun fact 1: marked (and therefore The Notebook) doesn't use CommonMark
Fun fact 2: The Notebook already uses at least 2 extensions (probably more): inline math with $...$ and raw LaTeX blocks that are interpreted as math.
(Just for future reference, the former might be built-in to marked sometime in the future (markedjs/marked#180))

I don't see a fundamental problem in adding another extension, if it keeps people from using HTML-exclusive work-arounds.

And sure, other tools will have to implement those extensions, too, but that's what happens already, see e.g. spatialaudio/nbsphinx#35.

@JanSchulz

Pandoc is circumstantial to this discussion, it's just another parser.

And I don't want to ignore errors in The Notebook. I want this to work correctly in The Notebook and also in all related tools I care about.

[takluyver]

I'm fine with extensions once there is a generic extensible syntax (see this discussion). What I want to avoid is doing ad-hoc extensions where someone picks some symbols and decides to make them mean a special thing, without regard for compatibility or conflicts.

I know we already make some extensions to the markdown the notebook supports. That does not mean it's OK to add more. Those extensions cause enough headaches, but so many notebooks already rely on them that we can't practically get rid of them.

I'm deliberately being hard on this, because I want to see a generic extension point in CommonMark, and that's not going to happen if we carry on doing ad-hoc extensions.

[mgeier]

@takluyver Thanks for the pointers. I've read a large part of the discussions (and there's a lot to read!), and it doesn't look like this extensible syntax is happening anytime soon. Development seems to go quite slowly currently, and the "base" syntax seems to have highest priority, since version 1.0 of the spec is already overdue.

I know we already make some extensions [...] we can't practically get rid of them.

And you shouldn't!
Those extensions are great, and the syntax is really simple and easy to use.
And being able to write equations in a straightforward way is one of the most important features of the Jupyter Notebook!

Anyway, I think the first step forward is to get rid of marked and switch to CommonMark. I've created a new issue about that: #1371.

Once this is done, I think we can continue discussing extensions.

[kmuehlbauer]

We recently changed our documentation workflow to integrate jupyter notebooks within our reST-documents. The reasons for that, we wanted to only document once. The notebooks can be utilized by the user and it is synced within the rendered docs (eg. using sphinx). The transition process went really smooth and we are happy to gain this much from using jupyter notebooks within our project.

However, these things can't be accomplished so far:

• admonitions
• citations

For admonitions I proposed some workaround for the 'nbsphinx' package (which we are using to convert the notebooks) spatialaudio/nbsphinx#46, which has it's faults, but works. Also in this issue here, several workarounds and hacks have been proposed, neither of which is really favourable.

From the users perspective things should just work. If there weren't the inline math available within the notebooks, this would have been a showstopper. And using <div> sections to get alert-boxes is (to some degree) annoying, too.

I understand, that the cleanest solution is to wait for the changes in the standard. But please also consider an interim extension which takes care of this until the changes are incorporated in the standard. Otherwise and this is already under-way, hacks, workarounds, incompatibilities will float around (just my 2c).

[mgeier]

For those who are interested: Since a proper solution will take a long time to come, I've implemented a temporary work-around in nbsphinx that converts <div> blocks with bootstrap warning and info classes to Sphinx boxes: http://nbsphinx.readthedocs.io/en/latest/markdown-cells.html#Info/Warning-Boxes