I’ve been searching for a good workflow for publishing Jupyter or RMarkdown Notebooks as static blog posts. I think I’ve found the optimal solution for my use case. In this post, I’ll explain my workflow and why chose this way with examples.
In reality my main purpose to migrate from Jekyll to Hugo was blogdown, thus R notebooks. Still, I have no regret even if I had not published any notebook yet.
Why Jupyter Notebooks Suck
Currently, I work with Python and usually with Jupyterlab Notebooks. I can’t say that I like jupyter notebooks. Still, they work fine for small projects and the notebook concept is good if you are taking notes or plotting graphs besides the code. What I don’t like about jupyter notebooks, is that they are JSON files. You may ask “what’s wrong with that?”. Well, let me tell you:
- You can’t just open jupyter notebooks in any code editor and edit them.
- Jupyter notebooks feel slower than normal code editors.
- I don’t like the extensions and the dependencies. Why would I install npm?
- It’s not as powerful as an IDE.
Most importantly, you can’t get clear diffs because notebooks are JSON files. I’ve tried an extension called
jupyterlab-git but the results weren’t satisfying for me.
So, I want:
- Normal diffs
- Ordinary text document
- Notebook logic
This is where Rmarkdown shines. Did you know that we can run Python code in Rmarkdown? R has a library called
reticulate which allows us to run Python via R. As a bonus, we have a fully-featured IDE RStudio.
Reticulate also allows us to combine R and Python code. Even though it’s an exciting feature, I don’t think most of us will need it. It might be useful for teams working on a big project.
Now, let’s take a step back and remember the main objective: Notebooks to Hugo. To be honest, I tried to convert jupyter notebooks to markdown using
jupyter nbconvert. It wasn’t successful. I’ve also tried a couple of scripts created by the community but the results weren’t good. You can try in your environment if you are already using jupyter notebooks.
This is a Rmarkdown document by the way and below is a Python code chunk. Let’s try it out.
Of course, my blog is already generated by Hugo and compatible with R blogdown library. So, I just simply did the following:
- open up RStudio
- open my existing website as a new R project.
- serve site using the add-ins or by running
- add post using the add-ins or create an Rmarkdown document or with
And it’s rendered auto-magically, I can now focus on the notebook. I suggest you use blogdown & hugo for ease of use but you can still use blogdown with other static site generators. Even more, you can write your notebook using Rmarkdown then convert it into the format you want using
knitr but that also requires learning about the knitr package.
In summary, we write in Rmarkdown. Blogdown converts it into markdown and then, Hugo processes the markdown file, generates an HTML file for publishing to the web.
Here are the most important benefits of using Rmarkdown for me:
- We are not dependent on Hugo or RStudio. You can work on VSCode if you want to.
- We can open the Rmarkdown document anywhere and read what’s inside.
- Most importantly, we have standard diffs with git.
As a side note, if you are using built-in syntax highlighters you should use
.Rmd. Otherwise, you’ll need a syntax highlighter library like
highlight.js. If you are already using client-side syntax highlighting then it shouldn’t matter which extension you choose.
In the next post, I’ll share examples of adding plots generated by Python code in the Rmarkdown document.