Way to export notebook as HTML in Jekyll for Blog Posts?

The problem I’m trying to solve is writing blog posts with Jupyter, but keep my Altair charts interactive. Furthermore, sometimes that I have widgets that would be nice to be available in my blog post for others to filter my charts etc. To maintain interactivity, I must export my notebook as HTML and not markdown.

When Jupyter notebooks get exported as HTML using nbconvert, all the dependencies are placed within the HTML file, such as the entire Bootstrap CSS framework. The bootstrap CSS framework tends to interfere with any Jekyll theme I have.

I am still learning front end, but does anyone have any ideas on strategies I can explore that allow me to only apply CSS to the notebook portion of the page and not the entire page? Through my research, the only thing I could find is using a react-based framework that allows me to localize CSS using CSS modules - however I do not want to move to a react-based framework like Gatsby for static sites and want to stay in Jekyll due to the integration with GitHub. Is there a way to achieve “component scoped CSS” with Jekyll? Or more generally, does anyone have any thoughts on concepts I can read up on that might solve this problem?

If I am thinking about this the completely wrong way and there is a completely different approach I should consider please let me know.

Thanks for your help.

cc: @jeremy @radek (b/c I think Radek knows a bit of Ruby and front end stuff, too).

P.S. For Altair, I’m using this template with nbconvert to inject the right javascript and other various elements to allow static page to render everything properly.

1 Like

I don’t think that this is possible. I probably wouldn’t be too much of a fan of going down the react path either. The only alternative that comes to mind is writing your own notebook exporter that would export to some simple HTML structure and styling that. Not sure how much work that would require. Other option might be a parser extracting only the NB part without style from the output of nbconvert.

Thanks Radek, this is really helpful. I will try writing a custom exporter via a export template as both you and Jeremy suggest

Might take me some time to figure it out some of the details and I’ll report back on this thread on what worked for me!

1 Like

Ok, folks, I figured it out. It turns out I don’t have to write any custom exporter or change any templates. Here is how you can embed interactive Jupyter notebooks with Altair in your GitHub Pages Jekyll blog.

  1. Copy this template locally. Name it altair_template.tpl . The reason for doing this is to include the dependencies for Altair in the HTML.

  2. Make a minor edit to this template. At the top, change

    {% extends "full.tpl" %}
    {% extends "basic.tpl" %}

  3. Create a Jupyter notebook with interactive charts using Altair. Note: the docs state that Ipywidgets are also supported by this (but I haven’t tested it yet)

  4. Convert your Jupyter Notebook to HTML by referencing the custom template .

    jupyter nbconvert your_notebook.ipynb --to html --template altair_template.tpl

  5. You can copy and paste this HTML in your markdown file for your Jekyll blog post, and it will not break any styling or CSS in your theme. It is definitely possible to automate this so you don’t have to copy and paste anything, I’m just so excited that I wanted to share this before creating automation that can do this (There is a way to do this in Jekyll or GitHub Actions).

  6. Enjoy your super cool blog with interactive, charts, graphs, tooltips, etc.

P.S. anyone interested in learning Altair, This tutorial is amazing


@hamelsmu can you share a link to the final result if it is public?

Warning I recommend not going down the rabbit hole of looking at my code as I haven’t made a simplified example just yet and (it’s easy to get lost in the other stuff that isn’t related to this subject at all), but I’ll provide this in case it is helpful since you asked

Repo: https://github.com/machine-learning-apps/mlops-dashboard

Result: (I’m hacking on it so may go down from time to time) https://machine-learning-apps.github.io/mlops-dashboard/

I’m working on a minimal example that is easier to understand as that repo has a bunch of other concerns not related to this…



Big thanks Hamel!
Trying to post as notebook. After pushing to repo nb not converted to post. As mentioned, first i have to make commit with /sync. Am i understand right - /sync should be in commit message?

Edited: i put /sync to commit with Nb. This way it triggered action.

Can you include a link to your repo so I can take a look?

Let me know if there could be a better user interface. Also see the README in the notebooks folder on instructions on how to customize

NB converted, but Pages not rebuilded yet.

Here what i have: action to convert nb to md start only if i use /sync in this commit name. Action for build pages start before convert, so no changes to _posts. So i have to do one more commit to start action. How to start action to rebuild pages without commit?

Any change to your master branch will rebuild your pages, however when your NB is converted your Pages will automatically start rebuilding. You can check your page build status in your repository settings, which will look like this

I understand logic. So it looks like bug. In my case, after commit first builds pages then nb convert. I can see it at actions - pages rebuild done but steel convertin nb.

Update to this thread for anyone watching, you don’t have to do any of these steps because it is currently automated in fast_template, see https://github.com/fastai/fast_template/tree/master/_notebooks

Also that repo is a good example of how to use nbdev on your own projects as well!

After i commit, nb2post convert nb, then commit. I got messege at github about this commit, but actions not starts and green check mark is absent.
How to trigger actions after script commit?

Following up here. The Jupyter/Word conversion automation in fast_template has been deprecated and has been moved to another project called fastpages. More details in this post: [fastpages] GitHub Pages Blog Using Nbdev