I tried converting the notebook to HTML but the results were horrible. Nikola and pelican(with plugin) support ipython notebook but I love hugo and would really love to use the notebooks on it. I would really appreciate it if someone can share a tip on how to successfully input an Ipython Notebook to a Hugo Site.
2 Likes
Nifty system, this Jupyter notebook.
Hugo markdown content files support embedding iframe tags or, you could use some javascript library if it exists. First see if you can get an “embed code” for a notebook, and then try putting it in an iframe tag, in a Hugo markdown file.
https://github.com/knowsuchagency/hugo_jupyter allows you to embed jupyter notebooks into a hugo website. However, it’d be nice if hugo could support jupyter notebooks by default. Jupyter notebooks are popular in blogs about programming.
I open a PR couple days ago to add support for iPython/jupyter notebook. And I agree with bep that it needs more discussion if we would want to officially support notebook file.
For anyone who is not familiar with Jupyter, it was originally a web interface with iPython. The project took off in popularity and changed to Jupyter to support more languages beside Python. List of supported languages: https://github.com/jupyter/jupyter/wiki/Jupyter-kernels
Jupyter notebook file is really great for writing, sharing, representing, and blogging about programming, as the code written in the post can also be executed. I did [a quick search prior to my PR to look for a way to get .ipynb file to work with Hugo, and that turned out I am not the only person with that problem, there are other attempts:
-
https://sharmamohit.com/post/jupyter-notebooks-in-blog, which proposes to convert the .ipynb to html and serves as static content. This has couple drawback: 1) we will have to maintain the CSS generated from jupyter, along with CSS used in Hugo theme; also, 2) the metadata will have to be manually created every time the HTML file is regenerate. The later point is really inconvenient for editing notebook file. -
https://github.com/knowsuchagency/hugo_jupyter(as also mentioned above). It usesfabfileto spin up 2 processes: 1 for jupyter and 1 for hugo. This has 2 drawback: 1) leaving an markdown .md file as footprint for converting between .ipynb to Hugo content, and 2) very easily leaves zombie process if either of the previous process is not terminated correctly. Unfortunately, that can happens easily in a Python land.
Since jupyter’s converter can work with standard i/o. It is promising to use the converter to convert .ipynb content to markdown content, then pass data in memory to Hugo’s markdown rendering, without using file system as a medium. From that perspective, it is similar the process flow that is currently used to pandoc content.
However, there is some weirdness that I hope to discuss. Hugo expects the frontmatter to be set at the beginning of each file. The .ipynb content is a big JSON object, and the frontmatter can only go to the property of the JSON object. That type of processing is very different from what I see in the code of Hugo, and I think would require another branch of processing for this type of content.
Even if we go with that direction, there are still some drawback: 1) I still don’t know how “Summary” would work in context of .ipynb, 2) Jupyter’s converter to markdown will loose the Input/Output count, this is currently the limitation of the converter 3) TableOfContent currently does not work well.
I don’t think there is a quick fix to make thing works perfectly. But I think there is low hanging fruit that can provide support for .ipynb content, that gives better drawback than what people are currently trying to hack around.
1 Like
Hey - this is awesome! I was just about to start working on the same thing and saw your PR.
With regards to the fontmatter at least, I had success just creating a “Raw NBConvert Cell” at the very top of the file as I’m editing the notebook. I agree this isn’t currently the most graceful solution, but this system does a good enough job to make the entire flow extremely useful. A similar approach can be used with summary (creating a raw cell with in it).
There’s some work to be done to get supporting files (images generated by nbconvert) to be in the right place, but I think (if I’m reading the docs correctly) that can be done through and arg.
Again - this is great. Makes working with Jupyter notebooks much easier!
I like your idea of using the first cell as the frontmatter. I am unfamiliar with “Raw NBConvert Cell” and can look more into it, but at least your idea works fine the using Markdown cell:
Result:
This makes editing frontmatter easier than using metadata.
With regard to Summary, I think positional checking (ie: 1st cell for frontmatter, optional 2nd cell for Summary) is error-prone. I think a better approach can be checking whether the cell ends with the Summary divider '<!— Summary --!>
Thank you very much the feedback!
Awesome! Didn’t even think of just throwing it as a markdown cell. Way easier.
The “Raw” cells just tell nbconvert not to touch the content there (say if you were throwing in some LaTeX) The Jupyter Notebook — Jupyter Notebook 7.0.6 documentation
@vhquang Are you still working on this? I’m just spinning up a Hugo blog and realised that Jupyter notebooks would be the best way for writing the type of content I’m interested in. Intutition says there should be a high demand for this, but not many people are talking about this functionality. I’m keen to contribute to the code, but not sure what would be required to submit a PR that will not get rejected.
@jklaise I am not working on this at the moment. I was eager to try thing out, when I was proposing the code change. What I should have done better is to open an issue, or a discussion to see how important this feature is to other Hugo users, and how many would be interested in it.
The change I propose has a different processing flow than what Hugo is designed for, so it will tax other maintainers to maintain my new change. So proper feedback is needed, before we make further change.
Alternatively, I have been thinking about making a Jupyter converter that will convert the notebook into a friendly format for Hugo. Then we can use it in the same way Hugo is currently using Pandoc. It won’t be in-memory and may leave temp files as footprint, but certainly lot less intrusive to Hugo as my original solution. No code has been done on this yet. Let me know your thought. I still try to figure out how many Hugo users are also interested with Jupyter.
1 Like
@vhquang @jklaise I built an nbconvert exporter to suit my needs for converting notebooks to a Hugo-friendly markdown format. You can take a look on Github if you’re interested. I’d love feedback!
I’m currently (kind of) a pelican user, but if Jupyter notebooks were a first class citizen of Hugo I would probably switch to Hugo. @jbandlow your exporter looks cool! I’ll check that out at some point.
1 Like
Thanks! If you ever do take a look, feedback is welcome!
Hey all - I’d just like to add another point of encouragement that .ipynb support would be fantastic. I’m working with the Jupyter project on a tool to host online “books” from notebooks, using an SSG (https://jupyter.org/jupyter-book). I want it runnable from the command line (e.g. provide a path to a folder w/ jupyter notebooks, and a file that denotes the “table of contents” and it’ll return the HTML for your book).
Currently it’s using Ruby, it converts the .ipynb files to Jekyll markdown, then builds the HTML with Jekyll. But I’d love to use Hugo as a backend for this instead (probably using the hugo book theme). @jbandlow your project looks great…I’ll give it a look!
3 Likes
I developed a very simple workflow to publish notebooks automatically. It uses a tool that I created some time ago, nb2hugo (https://github.com/vlunot/nb2hugo), as well as Netlify (and of course Hugo and Jupyter). For those interested in it, I created a very basic demo site at https://nb2hugo.netlify.com/.
Now, I just have to add my notebooks to my Git repository and they are automatically published on my blog. It is simple but fits my needs. Maybe it can be of interest for others.
4 Likes
there is a new issue related to this: Add support for parsing citations and Jupyter notebooks via Pandoc and/or Goldmark extension · Issue #6101 · gohugoio/hugo · GitHub