= Jupyter Notebook to HTML
:npm-name: ipynb2html
:gh-name: jirutka/{npm-name}
:gh-branch: master
:vs-marketplace-uri: https://marketplace.visualstudio.com/items?itemName=

ifdef::env-github[]
image:https://travis-ci.com/{gh-name}.svg?branch={gh-branch}[Build Status, link="https://travis-ci.com/{gh-name}"]
endif::env-github[]

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


== Packages

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


=== {npm-name}-core

ifdef::env-github[]
image:https://img.shields.io/npm/v/{npm-name}-core.svg[Version on npm, link="https://www.npmjs.org/package/{npm-name}-core"]
endif::env-github[]

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.

=== {npm-name}

ifdef::env-github[]
image:https://img.shields.io/npm/v/{npm-name}.svg[Version on npm, link="https://www.npmjs.org/package/{npm-name}"]
endif::env-github[]

This package builds on the {npm-name}-core and provides a complete, ready-to-go renderer configured with:

* https://github.com/markedjs/marked[marked] as Markdown renderer,
* https://github.com/KaTeX/KaTeX[KaTeX] as math renderer,
* https://github.com/IonicaBizau/anser[anser] as ANSI sequences renderer,
* https://github.com/highlightjs/highlight.js[highlight.js] as syntax highlighter.


ifndef::npm-readme[]

== Development

== System Requirements

* https://nodejs.org[NodeJS] 10.13+
* https://pandoc.org[Pandoc] and https://asciidoctor.org[Asciidoctor] (used only for converting README.adoc to Markdown for npmjs)


=== Used Tools

* https://www.typescriptlang.org[TypeScript] the language
* https://github.com/cevek/ttypescript[ttypescript] wrapper for `tsc` allowing to use custom AST transformers
* https://yarnpkg.com[yarn] for dependencies management and building
* https://eslint.org[ESLint] for linting JS/TypeScript code
* https://jestjs.io[Jest] for testing


=== How to Start

. Clone this repository:
[source, subs="+attributes"]
git clone https://github.com/{gh-name}.git

. Install Yarn (if you don’t have it already):
[source]
npm install -g yarn

. Install all JS dependencies:
[source]
yarn install

. Build the project:
[source]
yarn build

. Run tests and generate code coverage:
[source]
yarn test

. Run linter:
[source]
yarn lint

IMPORTANT: Keep in mind that JS sources are located in the `src` directories; `lib` directories contains transpiled code (created after running `yarn build`)!


=== Visual Studio Code

If you use Visual Studio Code, you should install the following extensions:

* link:{vs-marketplace-uri}ryanluker.vscode-coverage-gutters[Coverage Gutters]
* link:{vs-marketplace-uri}EditorConfig.EditorConfig[EditorConfig for VS Code]
* link:{vs-marketplace-uri}dbaeumer.vscode-eslint[ESLint]
* link:{vs-marketplace-uri}Orta.vscode-jest[Jest] (and link:{vs-marketplace-uri}shtian.jest-snippets-standard[Jest Snippets Standard Style])
* link:{vs-marketplace-uri}gamunu.vscode-yarn[yarn]

endif::[]


== Credits

* The renderer module is originally based on https://github.com/jsvine/notebookjs[notebookjs] 0.4.2 developed by https://github.com/jsvine[Jeremy Singer-Vine] and distributed under the http://opensource.org/licenses/MIT/[MIT License].
* The mathExtractor module is based on https://github.com/jupyter/notebook/blob/6.0.1/notebook/static/notebook/js/mathjaxutils.js[mathjaxutils.js] from the https://github.com/jupyter/notebook[Jupyter Notebook] 6.0.1 distributed under the https://github.com/jupyter/notebook/blob/6.0.1/COPYING.md[Modified BSD License].


== License

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