ipynb2pelican Plugin released!

Posted on Mon 27 March 2017 in Computer

Yet another Pelican Plugin for blogging with Jupyter Notebooks using MetaCell to store metadata.

Thanks to super cow power of python, we can finally publish ipynb easily! Below is the README.md from the project at this time.

The ipynb2pelican plugin provides markup for Jupyter/IPython notebooks in pelican, so .ipynb files are recognized as a valid filetype for an article.

MetaCell

The project is inspired by pelican-ipynb, but do things the other way: MetaCell (i.e. Metadata Cell). With MetaCell, there is NO need to create another metadata file, or edit ipynb externally. Everything is inside Jupyter Notebook!

Exact Idea of MetaCell is:

All and Only Metadata should be stored at the first Cell of ipynb

Writing a MetaCell is as simple as writting metadata in markdown file.

# This is title
+ date: 2020-02-22
+ tags: [hello, world]

Thanks to the markdown capability of ipynb, MetaCell will be shown like the following:

This is title

  • date: 2020-02-22
  • tags: [hello, world]

So, MetaCell itself will even enhance the readability of your notebooks!

Hint: In jupyter notebook, press Esc+M will switch selected cell to markdown mode.

Overview

The plugin is simple:

  • The CSS of jupyter will not be taken into outputs
  • The summary will be generated by Pelican

But it is still powerful and extensible:

  • Math Support
  • A Solution for metadata
  • Several configurable preprocessors provided
    • Metadata Extraction
    • SubCell Selection
    • Ignore cells with #ignore tag
    • Empty Cell Removal
  • You can change preprocess.py and define your own preprocessors

Preprocessors

Metadata Extraction

As we stated, All and Only Metadata should be stored at the first Cell of ipynb. If there is non-metadata content found, it will raise an exception. After the extraction of metadata, the MetaCell will be removed, as we have extracted all the information.

SubCells Selection

The Subcells preprocessor is executed after Metadata preprocessor (Th MetaCell it self will be removed by Metadata preprocessor), so zeroth cell is the first cell after MetaCell. The start and end should be written in the MetaCell like:

# This is title
+ date: 2020-02-22
+ tags: [hello, world]
+ subcells: [5, -1]

The value will be evaluated by start, end = ast.literal_eval(value). And then cells are sliced by cells[start:end].

Hint: If you want end to be infinity, use None

#ignore Tag

You can include an #ignore comment at the beginning of a cell of the Jupyter notebook to ignore it, removing it from the post content.

Note it is more strict than #ignore tag in pelican-ipynb. The purpose is to prevent kicking normal contents out of post content.

Remove Empty Cells

Remove trivial cells without visible characters using regular expression \S

Installation

Dependency

  • Currently works for python3 only
  • pelican
  • nbconvert
  • jupyter
  • ipython Download this repo and put all the .py files it into an ipynb directory into your plugins directory.

In the pelicanconf.py

MARKUP = ('md', 'ipynb')
PLUGIN_PATH = 'pelican-plugins'
PLUGINS = ['pelican-plugins']

Options

Option Default Meaning
IPYNB_REMOVE_EMPTY True Remove Empty Cells, True by default
IPYNB_IGNORE True Remove cells with #ignore tag at the beginning
IPYNB_SUBCELLS True Only preserve Subcells specified by subcells: [begin, end) metadata

TODO

  • Fix the inperfect environment support?
  • Syntax highlight for markdown cells

Acknowledgement

Thanks to pelican-ipynb! From reading the code of the project, I have learned how to write a similiar plugin with my own ideas.