Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Open
mgeier opened this issue Apr 1, 2016 · 15 comments
Milestone

Comments

@mgeier
Copy link
Contributor

@mgeier mgeier commented Apr 1, 2016

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

This comment has been minimized.

Copy link
Contributor

@Carreau Carreau commented Apr 1, 2016

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 !

@Carreau Carreau added this to the no action milestone Apr 1, 2016
@jankatins

This comment has been minimized.

Copy link
Contributor

@jankatins jankatins commented Apr 2, 2016

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

This comment has been minimized.

Copy link
Contributor Author

@mgeier mgeier commented Apr 7, 2016

@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:

@Carreau

This comment has been minimized.

Copy link
Contributor

@Carreau Carreau commented Apr 7, 2016

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

This comment has been minimized.

Copy link
Member

@takluyver takluyver commented Apr 7, 2016

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

This comment has been minimized.

Copy link
Contributor

@jankatins jankatins commented Apr 7, 2016

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

This comment has been minimized.

Copy link
Contributor Author

@mgeier mgeier commented Apr 8, 2016

@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

This comment has been minimized.

Copy link
Member

@takluyver takluyver commented Apr 8, 2016

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

This comment has been minimized.

Copy link
Contributor Author

@mgeier mgeier commented Apr 19, 2016

@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

This comment has been minimized.

Copy link

@kmuehlbauer kmuehlbauer commented Apr 26, 2016

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

This comment has been minimized.

Copy link
Contributor Author

@mgeier mgeier commented May 14, 2016

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

@JamiesHQ JamiesHQ closed this Apr 27, 2017
@mgeier

This comment has been minimized.

Copy link
Contributor Author

@mgeier mgeier commented Apr 27, 2017

@JamiesHQ Why did you close this?
Is there a solution available?

@JamiesHQ JamiesHQ reopened this Apr 27, 2017
@JamiesHQ

This comment has been minimized.

Copy link
Member

@JamiesHQ JamiesHQ commented Apr 27, 2017

@gnestor & @mpacer : what are the next steps on this issue? Thanks!

@gnestor

This comment has been minimized.

Copy link
Contributor

@gnestor gnestor commented Apr 27, 2017

There is no plan to implement something like this. However, I have seen several issues related to extending our markdown renderer, so I think the best thing to do is create an issue for implementing a general markdown extension interface so that we can start to act on things like this: #2450

@stevengj

This comment has been minimized.

Copy link

@stevengj stevengj commented Mar 27, 2019

Admonitions !!! foo are a common extension to Markdown, e.g. supported by mkdocs, in pandoc via an extension (jgm/pandoc#2610), and in flexmark via an extension. Julia's markdown docstrings commonly use them for warnings etcetera. Would be nice to have them in notebooks, but I understand that this is more of an upstream issue for you guys.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
8 participants
You can’t perform that action at this time.