README.md

JekyllNB: Jupyter Notebooks to Jekyll Markdown

JekyllNB extends Jupyter's command line tool nbconvert to add the Jekyll front matter to Markdown files and save generated images to a desired location. This allows you to easily convert all your notebooks to the required format and immediately build your Jekyll site. It works great in a GitHub Actions workflow to convert your notebooks to Markdown and deploy to GitHub Pages. See JekyllNB in action here.

Installation

JekyllNB is available on PyPI and can be installed with pip.

pip install jekyllnb

Usage

JekyllNB is a Jupyter app just like nbconvert. Call it with jupyter jekyllnb. The preprocessor reads metadata from your notebook to populate the Jekyll front matter. Add a jekyll section to your notebook metadata similar to:

"jekyll": {
    "layout": "notebook",
    "permalink": "/hello/",
    "title": "Hello World!"
}

The exporter will add the following front matter to the generated Markdown:

---
layout: notebook
permalink: /hello/
title: Hello World!
---

Options

Since jekyllnb extends nbconvert, all existing options are supported. The following new options are available:

• --site-dir: Root directory of your Jekyll site. Markdown (page-dir) and image (image-dir) folders will be created here if they do not exist.
• --page-dir: Directory for generated Markdown files (e.g. _pages or _posts).
• --image-dir: Directory for images. Images are organized into folders for each notebook by default. Alias for the nbconvert option NbConvertApp.output_files_dir.
• --no-auto-folder: Flag to turn off the default behavior of organizing images by notebook name within image-dir. (default: false)

nbconvert

JekyllNB also supports nbconvert by registering an entry point for the exporter. You can use the Jekyll exporter with nbconvert by calling jupyter nbconvert --to jekyll.

Note: The options above are not available with nbconvert.