Hacker News new | past | comments | ask | show | jobs | submit login
Jupyter Book (jupyterbook.org)
213 points by Datenstrom 8 days ago | hide | past | favorite | 54 comments

This looks quite geared towards generating the specific kind of interactive HTML book they show off. I guess that's because it's Sphinx under the hood. Looks useful for a specific kind of task!

Jupyter has a built-in templating system based on Pandoc (nbconvert) which is actually quite powerful. I have used it to generate print-ready documents via LaTeX templates.

For longer documents, one can use Pandoc JSON as an intermediary format, which can be assembled together before being output as LaTeX/PDF. For this one has to add a build tool like Make and not just the nbconvert command.

My biggest issue is that the nbconvert stuff is generally very hard to discover. It has very limited documentation which is further harmed by the considerable churn in the templating system, how they are discovered and how to plug them in to Jupyter lab. I suspect most people try "Export->PDF", see an ugly result with no obvious way to change it and give up. It's unfortunate because it's really a very powerful system under the hood.

Generating a paper or a technical note -- complete with beautiful typeset maths and figures -- from a computational document is really nice. Being able to take some data, generate a plot, calculate some values and put those values into prose such that the prose and the plot and the data are never out of sync is great! To me it's the next step up from having a referencing system so your references and bibliography are never out of sync.

What worked for me is using Python scripts ("filters") that do all required changes on the Pandoc JSON. I even ended up writing a pythonic layer on top of that JSON ("pip install panflute") so I wouldn't have to deal with the JSON itself.

We evaluated Jupyter Book against Read the Docs when building our new docs site (https://arcdocs.leeds.ac.uk/), the main reason we favoured Jupyter Book was that its easier to build and test locally and being able to use GitHub actions to build the html without relying on and being at the mercy of another third party service.

I wrote an intro to APL as a jupyterbook and found it an excellent tool for the job https://xpqz.github.io/learnapl

Hi, thanks for the link. I've had a look earlier today but didn't find any "print quality book output" that I can download as a PDF. Browsing your site, I can "Print to PDF" but that just gives me the webpage. Is there a way to get the full "offline" book, properly formatted? Thank you so much !

There is a full pdf in the repo (if you know where to look). I should sign-post it a bit better. https://github.com/xpqz/learnapl/blob/main/contents/_build/p...

https://quarto.org/ is also a good, and appears to be more flexible system, that I was recently recommended!

We use jupyterbook (geographicdata.science/book), and it has seriously simplified our workflow. The project is building useful features very quickly, and is very responsive to feedback & requests. Big props to their team.

https://executablebooks.org/en/latest/gallery.html has samples, looks great, reminds me of gitbook but better

Looks quite good. Reminds me of the R Bookdown project (https://bookdown.org/).

At some point last years I was fascinated with the jupyter ecosystem and was looking into something that could help making data analytic apps quick but not so dirty. Jupyter is the data side of thing, but the app side deviates so much from a standard web stack (react or web component) that it leaves much to be desired.

I am chipping away on a project called Evidence that might be of interest to you. Here’s the HN discussion from a couple weeks ago:


Has anyone made a note-taking tool (like notion/obsidian/logseq) that builds off of a computational notebook tool (like jupyter/observable/starboard)?

Mainly just needs wiki style links and backlinks and a search function.

There's Emacs's Org Mode.

nothing computational in there

That's not true. Org has a subsystem called Babel that can run code in lots of different languages, and it's pretty easy to add support for new ones.

Org Babel is the computational bit

it's a shame that "Show org source" is broken, but thanks, I'm intrigued.

I don't think this is true either. I went to one of the pages, https://orgmode.org/worg/org-contrib/babel/intro.html, clicked "Sow org source" and it took me to https://orgmode.org/worg/org-contrib/babel/intro.org.html, which does very nicely show the Org mode source code.

It's only broken on the front page, which tries to take you to https://orgmode.org.html/ when it should go to https://orgmode.org/worg/org-contrib/babel/index.org.html

If you want to see examples, look at the tutorial:


As for the source of that page, look at the Worg Maintenance section at https://orgmode.org/worg/

I haven't edited them yet, but I believe Worg is mostly org files on a Git repository - so you can clone it and see the source of all articles there.

mkdocs + mkdocs-material + mknotebooks

The general navigation / structure seems similar to ...

LEARN theme applied to a HUGO blog


Or is this a more common pattern that is implemented multiple ways?

Is there a simple worklfow to convert Markdown documents to a Hugo or JupyterBook site. I want to build some simple step-wise guides or workshop in this format -- and want to spend most of my time on content and less on the publishing tools and pipeline. Any advise appreciated -Thanks!

Looking into this for a course I'm putting together, but it executes all the notebooks to build the html which is a bit of a deal-breaker when downloading/training large DL models.

See: https://jupyterbook.org/content/execute.html

> To turn off notebook execution, change the above configuration value to:

``` execute: execute_notebooks: 'off' ```

Oh neat - must have been looking at an outdated note saying that it wasn't adjustable.

Note: you can create jupyter book with C# or F#


How does Jupyter ecosystem compare to traditional content management systems. Do people find it easier to customize with nbconvert? Does it play nicely with other web frameworks like Gatsby?

All I miss from nbsphinx is a "launch this in binder" button and a "edit this on github" button.

Is there DARK MODE support?

Is it just me or there is not way to download the entire book as pdf?

Unfortunately it seems to be converting to html and then "printing" to PDF so it will probably always look a bit janky compared to something that goes via LaTeX instead.

I built it using pdfhtml from source and it generated this PDF.


Not the cleanest one, but better than nothing.

There is a section that reads “ Build a PDF using LaTeX”.

It’s what I used with a nice weighty 5 gigabyte Tex installation.

Oh, nice! I stand corrected.

can you share the pdf?

I don't think so, definitely a feature that I would like.

looks like most of the documents are .md so you can use a markdown to pdf tool to generate a complete document

yes a high quality PDF output is essential.

In comparison, does anyone use Mathematica for authoring?

Yes, I used Mathematica to author https://quivergeometry.net, but I had to write the markdown converter, katex generator, rasterization caching etc. myself. Took a while to set up but works quite well now.

Some parts of it are quite flexible, like using Mathematica stylesheets to separate style and content for particular mathematical forms and change them globally to find the most ergonomic thing, with Katex that matches the mathematica (though I have to manually maintain that correspondence).

I do, and I consider jupyter to copy mathematica notebook, without seriously admitting it.

As shameless self promotion, if you’re interested in writing computational lessons for a course, check out Pathbird (pathbird.com), a SaaS product for creating guided computational lessons (targeted mostly towards university faculty right now but feel free to reach out if you’re interested).

We took a lot of inspiration from Jupyter Book (and use Jupyter kernels under the hood), so nothing but respect for all things Jupyter.

Once you have a publicly accessible demo, you should definitely make a Show HN of this! See https://news.ycombinator.com/showhn.html, https://news.ycombinator.com/item?id=22336638, https://news.ycombinator.com/yli.html for more info. (The last link gives instructions for YC startups launching on HN, but the basic principles apply more generally.)

Email hn@ycombinator.com if you want us to look over a draft (the same offer goes for anyone) - just please realize that we can't necessarily respond quickly; it depends on how brutal the inbox is that week/month.

I think it's cool that your homepage uses Julia code as an example for cell content:

  "Derivative of sigmoid function"
  function dsigmoid(z::Number)
    return ??
Wish you best of luck in your endeavors, seems like it has value and was born out of practical purposes

Where is the option to create a new course in Pathbird? I registered but only get an option to join an existing course with a code.

I write a lot of Jupyter notebooks at my main job and I also lecture at a university thus Pathbird seems relevant.

It’s currently “invite only” for instructors (mostly just to prevent abuse of the computational resources for, eg, crypto mining). If you shoot me a quick email (travis@pathbird.com) I’d be happy to set you up with a course.

You can demo the student experience with code JULIACON2020 as well.

This is interesting. I’ve been tinkering with using Jupyter Notebooks for our somewhat intensive onboarding of new engineers. Is Pathbird solely focused on the education market? Is there pricing info anywhere?

The original version of it was developed while teaching a data science course for non-CS grad students at the University of Michigan so most of our early efforts has been focused on the education market. My co-founder/advisor/UMich-professor has been using it to teach some courses outside UMich as well (namely https://pathbird.com/compml which is a very high quality math-focused DS course), so there's some precedent for it. If you're so inclined, feel free to shoot me an email (travis at pathbird.com) and I'd be happy to discuss things.

Pathbird looks really interesting. I am trying to understand what the main product is. One can design a curriculum and the lesson content is hosted in a Jupyter Notebook? If you were designing a course to teach a language, that language would have to be supported by Jupyter?

Thanks for the questions!

It’s not the Jupyter notebook (or lab) frontend, it’s a custom webapp built for learning and specifically around exercise based, guided learning. So a student will go through exercises (mostly multiple choice and code-based “autograded” exercises) to check their understanding and guide them through a lesson.

This style of learning tends to work best with interactive languages (Julia and Python and R at present). Theoretically we could support other languages with Jupyter kernels (including Go and C++, etc) as well. I wonder how well those languages would work in this context considering it’s a bit hard to be “iterative” with those (but consider than a challenge rather than a limitation!).

Feel free to reach out with any questions/comments/concerns and I can answer in more long form!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact