pelican-ipynb-reader

pelican-ipynb-reader is an independently maintained, static .ipynb reader for Pelican. Its source repository is a public successor-maintenance fork of danielfrg/pelican-jupyter. The archived upstream history and Apache-2.0 attribution are preserved. This distribution is not endorsed by the upstream author or the Pelican project.

Project status

Version 0.1.0 is the first supported independent release. It converts outputs already committed in notebooks and never executes cells or starts a kernel. Install the independent distribution:

python -m pip install pelican-ipynb-reader==0.1.0

The source remains at nekrasovp/pelican-jupyter to preserve the visible GitHub fork relationship and existing immutable commit links. The distribution name is intentionally separate from the historical pelican-jupyter project on PyPI. This project does not claim that historical name or access to it. See the independent identity decision.

Current public project documents:

• provenance and license;
• first-release contract;
• legacy-feature inventory;
• governance and contribution boundary;
• repository settings snapshot;
• PLUGIN-003 release-candidate evidence;
• release policy;
• public roadmap.

The PLUGIN-002 direct reader is merged. PLUGIN-003 added an independent publication-completeness gate, hosted compatibility matrix, synthetic fixtures, artifact inspection, and external 11-notebook evidence. The independent identity decision and release gates turn that accepted evidence into the supported 0.1.0 distribution.

First-release direction

The planned first release is a static Pelican reader for direct .ipynb article sources with adjacent .nbdata metadata. It converts outputs already committed in notebooks and never executes cells or starts a kernel. The first-release contract is the authoritative, self-contained scope for implementation and acceptance.

Liquid-tag embedding, Python 2, IPython 1.x fallbacks, nbconvert 5, and arbitrary historical templates are outside that release. They must not be treated as supported merely because their legacy code remains in this fork.

Usage

The implementation lives at pelican.plugins.ipynb_reader and registers an IPYNBReader through Pelican's readers_init signal. Load it explicitly:

MARKUP = ("ipynb",)
PLUGINS = ["pelican.plugins.ipynb_reader"]

For content/example.ipynb, create adjacent content/example.nbdata metadata:

Title: Synthetic Notebook
Date: 2026-07-21
Slug: synthetic-notebook
Tags: notebooks, synthetic
Category: Examples

The reader settings, stable metadata, failure model, and no-execution boundary are documented in the direct-reader contract.

Historical upstream usage

The archived project exposed two modes:

1. a direct .ipynb Pelican reader with adjacent .nbdata or metadata in the first notebook cell; and
2. Liquid-tag embedding of notebooks inside Markdown content.

The original configuration included settings such as Subcells, IPYNB_NB_SAVE_AS, IPYNB_GENERATE_SUMMARY, IPYNB_PREPROCESSORS, and custom nbconvert templates. These names are recorded for migration analysis in the legacy-feature inventory; they are not a successor compatibility promise.

For historical source and instructions, consult the archived upstream repository. Installing pelican-jupyter from PyPI installs the historical distribution, not pelican-ipynb-reader.

License

The upstream history and attribution are preserved. The repository remains licensed under the Apache License 2.0; see LICENSE.txt and the provenance note.