Allow the standalone export of a notebook to HTML #860

Closed
aarchiba opened this Issue Oct 11, 2011 · 12 comments

6 participants

@aarchiba

I often want to take an HTML notebook and post it on my blog. The procedure I use now is to hit "Print" and then view the source of the resulting static HTML. I then strip off the body tag and everything outside it; what remains I paste into an HTML view. This mostly works, but there are a few issues:

  • I needed to copy much of the CSS from various files into the custom CSS of my blog, and the rendering is still kind of wonky. It would be good to have a better-documented set of CSS that I could embed, and maybe even customize.

  • Multiple figures in one cell are all rendered on one line, for some reason. It's a pain to manually edit in <br /> between each one. Maybe this is a CSS issue?

  • It would be nice to put a newline or two after the opening body tag and before the closing, to make the stripping process easier.

There's an example of the output at http://lighthouseinthesky.blogspot.com/2011/10/testing-whether-signal-is-broad-band.html

@ellisonbg
IPython member
@aarchiba

Well, my point is that you are very nearly there; basically, if the three points above are addressed, it'll be perfectly usable.

@fperez
IPython member

We're too close to release time to realistically think we can get this done by 0.12, but I've tagged it for 0.13 and hopefully we can indeed make that happen. My hope is that once we get the nb out in public, more contributors will appear who know/like js/css work and will be willing to help with this kind of thing. We've had similar good outcomes with contributions to the qt console, so I think my optimism isn't completely misplaced.

@ellisonbg
IPython member

This will be worked on in coming notebook refactoring. I am going to leave it open to track its progress.

@fperez
IPython member

We've been needing this for a while, so I hacked together something real quick. This is not final code, but it should do the trick for now in simple cases. We'll build this into proper code into ipython later on, but I figured something like this would be cleaner than the manual css hacking many people seem to be doing and that @aarchiba mentions above. Anne, let us know if it gets the basic job done, and we can then use it as the starting point for something cleaner.

@ellisonbg
IPython member
  • The IPython.nbformat.v3 subpackage has an infrastructure for notebook readers/writers. We currently have one for .json and .py files. This is the place to create one for exporting to HTML.
  • Exporting to raw HTML is not quite possible. The reason for this is that we use a couple of Javascript libraries: MathJax for rendering latex embedded in the HTML, CodeMirror for formatting the code areas with syntax highlighting, and A Markdown parser that converts Markdown to HTML. We will have to figure out substitutes for these JS libraries in the HTML export.
  • There are two possible ways of generating raw HTML:

1) First export to reST and then use rst2html to get to the HTML. Some benefits to this, but the downside is that raw Markdown/HTML cells would get lost in the process (although I think that reST suports raw HTML inclusion. Also, this would make it more difficult to control exactly what the HMTL looks like (IOW use our current CSS styling).
2) Use a templating library to export directly to HTML. I think this is very worth pursuing as a first line of attack. The would allow you to simply recreate the right HTML structure with the proper id/classes and then inline our CSS. It would give you exactly the same look as we have now. We would still need to figure out how to handle MathJax, CodeMirror and Markdown though.

I imagine that in the long run we will support both of these routes. Once we have the writers in place in IPython.nbformat.v3, it will be a simple matter of incorporating them into the notebook server.

@ellisonbg
IPython member

Also relevant for converting Markdown to HTML:

http://www.freewisdom.org/projects/python-markdown/

@markvoorhies

I like the two approaches Brian outlined because they should not be dependent on the browser (so, should play better with non-html notebooks in the future), but I'm also curious how far we could get through introspection in the browser (weakly analogous to using Qt's internal HTML representation for HTML export in the qtconsole). Probably not the right approach, but possibly useful for exploring or generating test cases.

@bgbg

Was there any progress with this issue?

@fperez
IPython member

Yes, some: we now have a full repository called nbconvert where conversion code lives. It's still pretty rough, which is why we haven't merged it into mainline ipython, but all help on improving that code is welcome.

I hope we'll be able to merge it for the 0.14 release cycle.

@bgbg

cool. thank you for your work

@minrk
IPython member

nbconvert is merged. There is still work to do, but closing this as addressed.

@minrk minrk closed this Jul 4, 2013
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment