Skip to content


Folders and files

Last commit message
Last commit date

Latest commit


Repository files navigation

A simple SoS workflow to generate website from Jupyter notebooks

Copyright 2016 Gao Wang

Run from a docker image

  1. Install docker. Double-check after installation that docker is properly installed, by typing:

    docker run hello-world
    # Hello from Docker.
    # This message shows that your installation appears to be working correctly.
  2. Pull the docker image that contains dependency software to generate the website:

    docker pull gaow/jnbinder
  3. Download the script from this repository to your project folder and load it:


    After this, command prompt jnbinder should be available from your terminal. To verify, the following command should display the command interface:

    jnbinder -h
  4. If it is your first time using this program please run the following to initialize:

    jnbinder setup-jnbinder

    Then open up the file config.yml and edit it, particularly set the include_dir to point to where your Jupyter notebooks are. A simplified example can be found here.

  5. Inside your new project directory, generate all the webpages using the following command:

  6. Next time when you generate the files, if you want to skip existing pages please type jnbinder -s build. If you want to force generate every page from scratch you can use:

    jnbinder clean
    jnbinder -s force

[For advanced users only] Run source code

This works only with Jupyter version 2.x

Step 0: install dependencies

pip install sos bs4 

Step 1: install jnbinder

chmod +x release
./release setup-jnbinder

Step 2: edit config.yml to include notebooks under various folders

See the template config.yml file in this repo. Uncomment them as you customize the contents. Particularly, configure include_dir to include folders where you keep the notebooks you want to publish as HTML pages. Here is a minimal example configuration file in action. To reproduce it you can download some example notebooks here and put them to a folder (or multiple folders) consistent with what's specified in include_dir.

Step 3: build website

./release -j 10

Or, when things go wrong (pages not updated as expected).

./release -s force -j 10

where -j 10 means running 10 conversion commands in parallel -- useful when there is a lot of notebooks to bind.

You should see the result in docs/ folder. You can click on docs/index.html to open it in your browser.

Mics: upgrade jnbinder

./release upgrade-jnbinder

The software is intented for my personal use but I'm happy to help if you request a feature or report a bug (it is not fully documented so do not worry about requesting for features that already exist!).

Here are more examples of generated research websites:


Repository of Jupyter Notebooks






No releases published


No packages published