Skip to main content

Convert Jupyter Notebooks to Jekyll-ready Markdown files

Project description

JekyllNB: Jupyter Notebooks to Jekyll Markdown

Test Status Documentation Status Coverage Status LGTM DeepSource PyPI Version Downloads License Code Style

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.


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

pip install jekyllnb


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!


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)


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.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jekyllnb, version 0.3.1
Filename, size File type Python version Upload date Hashes
Filename, size jekyllnb-0.3.1-py3-none-any.whl (7.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size jekyllnb-0.3.1.tar.gz (6.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page