Raku Jupyter::Converter

In brief

Jupyter converters of Jupyter files into files of different kind of formats:

• DONE HTML file

• DONE Markdown file

• DONE Mathematica notebook

• DONE Org-mode file

• DONE Pod6 file

• DONE Raku data structure

Related work

• The Raku package "Markdown::Grammar", [AAp1], has a similar mission for Markdown files (or strings.)

• Pandoc attempts to be a universal converter, applicable for all couples of formats of this package.

Installation

From Zef ecosystem:

zef install Jupyter::Converter

From GitHub:

zef install https://github.com/antononcube/Raku-Jupyter-Converter.git

Round trip translation

Consider the following round trip translation experiment:

1. Make a Jupyter notebook

2. Convert Jupyter notebook into Markdown file with the Raku package "Jupyter::Converter"

3. Convert the obtained Markdown file into Jupyter notebook using the Raku package "Markdown::Grammar"

4. Compare the notebooks

Here is the corresponding flowchart:

Command line interface

The package provides a Command Line Interface (CLI) script, from-jupyter. Here is its usage message:

from-jupyter --help

# Usage:
#   from-jupyter <text> [-t|--format|--to=<Str>] [--img-dir|--image-directory=<Str>] [-m|--method=<Str>] [-o|--output=<Str>] [--<args>=...] -- Converts Jupyter notebooks into Markdown, HTML, and Pod6 files.
#   
#     <text>                               Input file or Jupyter notebook text.
#     -t|--format|--to=<Str>               Format to convert to. (One of 'html', 'markdown', 'mathematica', 'org-mode', 'pod6', 'raku', or 'Whatever'.) [default: 'Whatever']
#     --img-dir|--image-directory=<Str>    Directory to export images to. [default: 'Whatever']
#     -m|--method=<Str>                    Method of conversion. (One of 'delegation' or 'Whatever'.) [default: 'Whatever']
#     -o|--output=<Str>                    Output file; if an empty string then the result is printed to stdout. [default: '']
#     --<args>=...                         Arguments to pass to `from-markdown`.

The CLI script from-jupyter takes both file names and (Markdown) text. Here is an usage example for the latter:

Remark: If CLI script's argument --output is a non-empty string and --to is "whatever" or "automatic", then an attempt is made to conclude the format to convert to from the extension of the file name given to --output.

The CLI (and from-jupyter) take a method option, which, if set to "delegation" converts the Jupyter notebook to Markdown text and then uses from-markdown of "Markdown::Grammar", [AAp1].

More elaborated conversions can be done with shell pipelines. For example:

from-jupyter resources/demo.ipynb --to=markdown | from-markdown -r=RakuInputExecute | pbcopy

TODOs

The most important items are placed first.

• DONE Markdown: export SVG images into an image directory

  • And use the links to those images in the Markdown output.

• DONE Delegate to "Grammar::Markdown" for conversion

  • DONE Simple delegation for Mathematica and Org-mode

  • DONE Have a method option in from-jupyter

  • DONE Corresponding CLI changes

  • I am not sure how needed this functionality is, after I made from-markdown being able to take pipeline input.

    • See "Markdown::Grammar:ver<0.6.4>:authzef:antononcube:api<1>"

• TODO Compare package's HTML and POD6 converters outputs to those of "Markdown::Grammar"

References

Articles

[AA1] Anton Antonov, "Notebook transformations", (2024), RakuForPrediction at WordPress.

Guides

[JG1] John Gruber, Markdown: Syntax.

[MC1] Matt Cone, Markdown Guide.

[RC1] Raku Community, Raku Pod6.

Packages

[AAp1] Anton Antonov, Markdown::Grammar, Raku package, (2022-2025), GitHub/antononcube.

Videos

[AAv1] Anton Antonov, "Markdown to Mathematica converter (CLI and StackExchange examples)", (2022), Anton A. Antonov's channel at YouTube.

[AAv2] Anton Antonov, "Markdown to Mathematica converter (Jupyter notebook example)", (2022), Anton A. Antonov's channel at YouTube.

[AAv3] Anton Antonov, "Conversion and evaluation of Raku files", (2022), Anton A. Antonov's channel at YouTube.