Added support for jupyter notebooks #417 (#1511)

Implemented #417.

---------

Signed-off-by: George Araújo <george.gcac@gmail.com>
Co-authored-by: Amir Pourmand <pourmand1376@gmail.com>

.github/workflows/deploy.yml

@@ -16,6 +16,7 @@ permissions:
 
 jobs:
   deploy:
+    # available images: https://github.com/actions/runner-images#available-images
     runs-on: ubuntu-latest
     steps:
     - name: Checkout 🛎️
@@ -27,6 +28,7 @@ jobs:
         bundler-cache: true
     - name: Install and Build 🔧
       run: |
+        pip3 install --upgrade jupyter
         npm install -g mermaid.cli
         export JEKYLL_ENV=production
         bundle exec jekyll build

Dockerfile

@@ -1,24 +1,35 @@
 FROM bitnami/minideb:latest
 Label MAINTAINER Amir Pourmand
 RUN apt-get update -y
+
 # add locale
 RUN apt-get -y install locales
 # Set the locale
 RUN sed -i '/en_US.UTF-8/s/^# //g' /etc/locale.gen && \
     locale-gen
-ENV LANG en_US.UTF-8  
+ENV LANG en_US.UTF-8
-ENV LANGUAGE en_US:en  
+ENV LANGUAGE en_US:en
-ENV LC_ALL en_US.UTF-8  
+ENV LC_ALL en_US.UTF-8
 
 # add ruby and jekyll
-RUN apt-get install --no-install-recommends ruby-full build-essential zlib1g-dev -y 
+RUN apt-get install --no-install-recommends ruby-full build-essential zlib1g-dev -y
-RUN apt-get install imagemagick -y 
+RUN apt-get install imagemagick -y
+
+# install python3 and jupyter
+RUN apt-get install python3-pip -y
+RUN python3 -m pip install jupyter --break-system-packages
+
+# clean everything
 RUN apt-get clean \
     && rm -rf /var/lib/apt/lists/
+RUN pip3 cache purge
+
 # ENV GEM_HOME='root/gems' \
 #     PATH="root/gems/bin:${PATH}"
+
+# install jekyll and dependencies
 RUN gem install jekyll bundler
 RUN mkdir /srv/jekyll
 ADD Gemfile /srv/jekyll
 WORKDIR /srv/jekyll
-RUN bundle install
+RUN bundle install

Gemfile

@@ -7,6 +7,7 @@ group :jekyll_plugins do
     gem 'jekyll-email-protect'
     gem 'jekyll-feed'
     gem 'jekyll-imagemagick'
+    gem 'jekyll-jupyter-notebook'
     gem 'jekyll-link-attributes'
     gem 'jekyll-minifier'
     gem 'jekyll-paginate-v2'

_config.yml

@@ -222,6 +222,7 @@ plugins:
   - jekyll-email-protect
   - jekyll-feed
   - jekyll-imagemagick
+  - jekyll-jupyter-notebook
   - jekyll-link-attributes
   - jekyll-minifier
   - jekyll-paginate-v2

_plugins/file-exists.rb

@@ -0,0 +1,23 @@
+module Jekyll
+    class FileExistsTag < Liquid::Tag
+
+        def initialize(tag_name, path, tokens)
+            super
+            @path = path
+        end
+
+        def render(context)
+            # Pipe parameter through Liquid to make additional replacements possible
+            url = Liquid::Template.parse(@path).render context
+
+            # Adds the site source, so that it also works with a custom one
+            site_source = context.registers[:site].config['source']
+            file_path = site_source + '/' + url
+
+            # Check if file exists (returns true or false)
+            "#{File.exist?(file_path.strip!)}"
+        end
+    end
+end
+
+Liquid::Template.register_tag('file_exists', Jekyll::FileExistsTag)

_posts/2015-07-15-code.md

@@ -64,7 +64,7 @@ By default, it does not display line numbers. If you want to display line number
 
 If you want to display line numbers for a specific code block, all you have to do is wrap your code in a liquid tag:
 
-{% raw  %}
+{% raw %}
 {% highlight c++ linenos %}  <br/> code code code <br/> {% endhighlight %}
 {% endraw %}
 

_posts/2023-07-04-jupyter-notebook.md

@@ -0,0 +1,41 @@
+---
+layout: post
+title: a post with jupyter notebook
+date: 2023-07-04 08:57:00-0400
+description: an example of a blog post with jupyter notebook
+categories: sample-posts jupyter-notebook
+giscus_comments: true
+related_posts: false
+---
+
+To include a jupyter notebook in a post, you can use the following code:
+
+{% raw %}
+
+```html
+{::nomarkdown}
+{% assign jupyter_path = "assets/jupyter/blog.ipynb" | relative_url %}
+{% capture notebook_exists %}{% file_exists assets/jupyter/blog.ipynb %}{% endcapture %}
+{% if notebook_exists == "true" %}
+    {% jupyter_notebook jupyter_path %}
+{% else %}
+    <p>Sorry, the notebook you are looking for does not exist.</p>
+{% endif %}
+{:/nomarkdown}
+```
+
+{% endraw %}
+
+Let's break it down: this is possible thanks to [Jekyll Jupyter Notebook plugin](https://github.com/red-data-tools/jekyll-jupyter-notebook) that allows you to embed jupyter notebooks in your posts. It basically calls [`jupyter nbconvert --to html`](https://nbconvert.readthedocs.io/en/latest/usage.html#convert-html) to convert the notebook to an html page and then includes it in the post. Since [Kramdown](https://jekyllrb.com/docs/configuration/markdown/) is the default Markdown renderer for Jekyll, we need to surround the call to the plugin with the [::nomarkdown](https://kramdown.gettalong.org/syntax.html#extensions) tag so that it stops processing this part with Kramdown and outputs the content as-is.
+
+The plugin takes as input the path to the notebook, but it assumes the file exists. If you want to check if the file exists before calling the plugin, you can use the `file_exists` filter. This avoids getting a 404 error from the plugin and ending up displaying the main page inside of it instead. If the file does not exist, you can output a message to the user. The code displayed above outputs the following:
+
+{::nomarkdown}
+{% assign jupyter_path = "assets/jupyter/blog.ipynb" | relative_url %}
+{% capture notebook_exists %}{% file_exists assets/jupyter/blog.ipynb %}{% endcapture %}
+{% if notebook_exists == "true" %}
+    {% jupyter_notebook jupyter_path %}
+{% else %}
+    <p>Sorry, the notebook you are looking for does not exist.</p>
+{% endif %}
+{:/nomarkdown}

assets/jupyter/blog.ipynb

@@ -0,0 +1,48 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "collapsed": false
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "sys.version_info(major=3, minor=6, micro=2, releaselevel='final', serial=0)"
+      ]
+     },
+     "execution_count": 1,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "import sys\n",
+    "sys.version_info"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.6.2"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}