ipynb2html is a converter (renderer) of the [Jupyter Notebook
Format](https://nbformat.readthedocs.io/en/stable/) 4.0+ to static HTML.
It works both in Node.js and browser environment.

Packages
--------

This repository contains the following packages, all published on
[npm](https://www.npmjs.com/).

### ipynb2html-core

This package provides the converter itself and some utilities with **no
dependencies**. You have to provide your own syntax highlighter and
Markdown, math and ANSI sequences renderer; or not, if you don’t need
them.

### ipynb2html

This package builds on the ipynb2html-core and provides a complete,
ready-to-go renderer configured with:

-   [marked](https://github.com/markedjs/marked) as Markdown renderer,

-   [KaTeX](https://github.com/KaTeX/KaTeX) as math renderer,

-   [anser](https://github.com/IonicaBizau/anser) as ANSI sequences
    renderer,

-   [highlight.js](https://github.com/highlightjs/highlight.js) as
    syntax highlighter.

It also provides a reference stylesheet which you can find in
`dist/notebook.min.css` (or non-minified
[`styles/notebook.css`](packages/ipynb2html/styles/notebook.css)).

### ipynb2html-cli

This package provides a CLI interface for ipynb2html.

Usage
-----

### CLI

    ipynb2html notebook.ipynb notebook.html

Run `ipynb2html --help` for more information.

### Node.js (server-side)

To render HTML in Node.js (server-side rendering), you need some (fake)
DOM implementation. The recommended one is
[nodom](https://github.com/redom/nodom/) — it’s lightweight,
[small](https://bundlephobia.com/result?p=nodom), doesn’t have any
external dependencies and ipynb2html is tested against it. However, you
can choose any other if you like.

    npm install ipynb2html nodom

``` js
import * as fs from 'fs'
import * as ipynb from 'ipynb2html'
import { Document } from 'nodom'

const renderNotebook = ipynb.createRenderer(new Document())

const notebook = JSON.parse(fs.readFileSync('./example.ipynb', 'utf8'))

console.log(renderNotebook(notebook).outerHTML)
```

### Browser (client-side)

You have basically two options how to use ipynb2html in the browser: use
the browser bundles provided in the ipynb2html package, or build your
own bundle (using e.g. [Rollup](https://rollupjs.org) or
[webpack](https://webpack.js.org/)).

The provided bundles are in UMD format (AMD, CommonJS and IIFE in one
file), so they should work in all environments (old and modern browsers,
Node.js). They are transpiled and have injected
[core-js](https://github.com/zloirock/core-js/) polyfills to be
compatible with browsers that have [&gt;0.5% global coverage, Firefox
ESR, and not dead
browsers](https://browserl.ist/?q=%3E0.5%25%2C+Firefox+ESR%2C+not+dead).

#### Full Bundle

`ipynb2html-full.min.js` is a self-contained bundle with all the
external dependencies included (marked, KaTeX, Anser and Highlight.js).

You can link it from [jsDelivr CDN](https://www.jsdelivr.com/), for
example:

``` html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ipynb2html@0.4.0-rc.1/dist/notebook.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.7.3/build/styles/default.min.css" crossorigin="anonymous">
    <script src="https://cdn.jsdelivr.net/npm/ipynb2html@0.4.0-rc.1/dist/ipynb2html-full.min.js" crossorigin="anonymous"></script>
  </head>
  ...
</html>
```

The bundle exposes global variable `ipynb2html`:

``` js
const element = ipynb2html.render(notebook)
document.body.appendChild(element)
```

ipynb2html also provides function `autoRender` that renders each
notebook on the page embedded (as JSON) inside
`<script type="application/x-ipynb+json">...</script>`.[1]

``` html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ipynb2html@0.4.0-rc.1/dist/notebook.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.7.3/build/styles/default.min.css" crossorigin="anonymous">
    <script defer src="https://cdn.jsdelivr.net/npm/ipynb2html@0.4.0-rc.1/dist/ipynb2html-full.min.js" crossorigin="anonymous"
        onload="ipynb2html.autoRender();"></script>
  </head>
  <body>
    <main>
      <script type="application/x-ipynb+json">
        {
          "cells": [ ... ],
          "metadata": { ... },
          "nbformat": 4,
          "nbformat_minor": 3
        }
      </script>
    </main>
  </body>
<html>
```

#### Slim Bundle

`ipynb2html.min.js` contains only ipynb2html and ipynb2html-core code
(plus polyfills). If you load marked, KaTeX, AnsiUp, and Highlight.js in
the page, you will get the same functionality as with
`ipynb2html-full.min.js`:

``` html
<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.css" crossorigin="anonymous">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.7.3/build/styles/default.min.css" crossorigin="anonymous">
    <script src="https://cdn.jsdelivr.net/npm/marked@4.1.1/marked.min.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/ansi_up@5.0.1/ansi_up.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/gh/highlightjs/cdn-release@10.7.3/build/highlight.min.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/katex@0.16.3/dist/katex.min.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/ipynb2html@0.4.0-rc.1/dist/ipynb2html.min.js" crossorigin="anonymous"></script>
  </head>
  ...
</html>
```

Or you may use any other implementations and provide them to the
`ipynb2html.createRenderer` function. All of them are optional, but you
usually need at least a Markdown renderer.

Credits
-------

-   The renderer module is originally based on
    [notebookjs](https://github.com/jsvine/notebookjs) 0.4.2 developed
    by [Jeremy Singer-Vine](https://github.com/jsvine) and distributed
    under the [MIT License](http://opensource.org/licenses/MIT/).

-   The mathExtractor module is based on
    [mathjaxutils.js](https://github.com/jupyter/notebook/blob/6.0.1/notebook/static/notebook/js/mathjaxutils.js)
    from the [Jupyter Notebook](https://github.com/jupyter/notebook)
    6.0.1 distributed under the [Modified BSD
    License](https://github.com/jupyter/notebook/blob/6.0.1/COPYING.md).

License
-------

This project is licensed under [MIT
License](http://opensource.org/licenses/MIT/). For the full text of the
license, see the [LICENSE](LICENSE) file.

[1] Don’t forget to escape HTML special characters: `<`, `>`, and `&`.
