Fixed html doc usage docs to fix 6.x #1386
Conversation
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
|
|
||
| Simplified HTML, useful for embedding in webpages, blogs, etc. | ||
| This excludes HTML headers. | ||
| Simplified HTML, using the classic jupyter look and feel. |
There was a problem hiding this comment.
I think it might be useful to also document the “embeddable” version, which would be --template-file=classic/base.html.j2 (or lab/)
There was a problem hiding this comment.
--template=classic is preferred over --template-file=classic/base.html.j2. It's possible in a future release that when the backwards compatibility is removed that the second pattern might not work that way anymore (--template=classic --template-file=notbase.html.j2 might be required in some distance release, or no support template-file at all). https://nbconvert.readthedocs.io/en/6.0.2/changelog.html?highlight=--template-file#id3 outlines how to use template-file to refer to a specific .tpl 5.x file.
I'm hesitant to promote it more elsewhere for other uses because some of these always-supported patterns made the 6.0 upgrade harder. But I could be convinced it's a good idea to document it more if people feel strongly about it.
There was a problem hiding this comment.
--template=classic is not a replacement for basic/classic/base.html.j2, because it produces a full 13k line (?!) HTML document with styles and JS. This is not usable for embedding, at least not without using a HTML parser to get rid of the 13k lines of <head>. classic/base.html.j2 produces just the notebook code and expects styles to be added in elsewhere (and we do it that way in Nikola).
There was a problem hiding this comment.
Hmm you're correct. I wasn't as involved with the html template changes from 5.x to 6.x. It looks like adding --template-file=base.html.j2 along with --template=classic gets you back to close to the original --template=base pattern without all the styles and JS. Can you try that and see if it matches expectations? I can discuss with the other maintainers how to better preserve that capability in a clearer format with the new system if so.
There was a problem hiding this comment.
It seems to work, both from the command line and code. It would be good to have an officially recommended way to do this in the docs.
There was a problem hiding this comment.
I agree. Thanks for raising the concern and documentation gap. I'll talk with the other maintainers and see if we want to introduce an easier way to run this combination before I document it, but I don't believe we'll remove the pattern that worked for you here.
Partially resolves #1384