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.

Source Distribution

jekyllnb-0.3.1.tar.gz (6.7 kB view hashes)

Uploaded source

Built Distribution

jekyllnb-0.3.1-py3-none-any.whl (7.8 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page