README
ΒΆ
nb
Render Jupyter Notebooks in pure Go π
This package is inspired by @yuin's goldmark and is designed to be as clear and extensible.
The implementation follows the official Jupyter Notebook format spec (nbformat) and produces an output similar to that of nbconvert (Jupyter's team own reference implementation) both structurally and visually. It supports all major nbformat schema versions: v4.0-v4.5, v3.0, v2.0, v1.0.
The package comes with an HTML renderer out of the box and can be extended to convert notebooks to other formats, such as LaTeX or PDF.
π This package is being actively developed: its structure and APIs might change overtime.
If you find any bugs, please consider opening an issue or submitting a PR.
Installation
go get github.com/bevzzz/nb
Usage
nb's default, no-frills converter can render markdown, code, and raw cells out of the box:
b, err := os.ReadFile("notebook.ipynb")
if err != nil {
panic(err)
}
err := nb.Convert(os.Stdout, b)
To produce richer output nb relies on a flexible extension API and a collection of built-in adapters and standalone extensions that allow using other packages to render parts of the notebook:
import (
"github.com/bevzzz/nb"
synth "github.com/bevzzz/nb-synth"
"github.com/bevzzz/nb/extension"
"github.com/bevzzz/nb/extension/adapter"
jupyter "github.com/bevzzz/nb/extension/extra/goldmark-jupyter"
"github.com/robert-nix/ansihtml"
"github.com/yuin/goldmark"
highlighting "github.com/yuin/goldmark-highlighting/v2"
)
md := goldmark.New(
goldmark.WithExtensions(
jupyter.Attachments(),
highlighting.Highlighting,
),
)
c := nb.New(
nb.WithExtensions(
jupyter.Goldmark(md),
synth.Highlighting,
extension.NewStream(
adapter.AnsiHtml(ansihtml.ConvertToHTML),
),
),
)
err := nb.Convert(os.Stdout, b)
The snippet above uses these additional dependencies:
goldmarkwithgoldmark-jupyterchromawithnb-synthansihtmlwith built-inadapters.AnsiHtml
It's a combination of packages that worked really well for me; I encourage you to play around with this example CLI to see how it renders different kind of notebooks.
Extending nb does not end here. Your project may already use a different Markdown renderer, or require custom handling of certain mime-/cell types, in which case I hope the existing extensions will serve as useful reference implementations.
Styling the notebook: batteries included π
nb comes with the Jupyter's classic light theme, which you can capture by passing a dedicated CSSWriter and adding it to the final HTML.
Mind that the default theme is ~1000 lines long and might not fit the existing style in a more complex project.
In that case you probably want to write your own CSS.
Click to expand
// Write both CSS and notebook's HTML to intermediate destinations
var body, css bytes.Buffer
// Configure your converter
c := nb.New(
nb.WithRenderOptions(
render.WithCellRenderers(
html.NewRenderer(
html.WithCSSWriter(&css),
),
),
),
)
err := c.Convert(&body, b)
if err != nil {
panic(err)
}
// Create the final output
f, _ := os.OpenFile("notebook.html", os.O_RDWR, 0644)
defer f.Close()
f.WriteString("<html><head><style>")
io.Copy(f, &css)
f.WriteString("</style></head>")
f.WriteString("<body>")
io.Copy(f, &body)
f.WriteString("</body></html>")
Roadmap πΊ
- v0.4.0:
- Built-in pretty-printing for JSON outputs
- Custom CSS (class prefix / class names).
I really like the way
chromaexposes its styling API and I'll try to do something similar.
- Other:
- I am curious about how
nb's performance measures against other popular libraries likenbconvert(Python) andquarto(Javascript), so I want to do some benchmarking later. - As of now, I am not planning on adding converters to other formats (LaTeX, PDF, reStructuredText), but I will gladly consider this if there's a need for those.
- I am curious about how
If you have any other ideas or requests, please feel welcome to add a proposal in a new issue.
Miscellaneous
Math
Since Jupyter notebooks are often used for scientific work, you may want to display mathematical notation in your output.
MathJax is a powerful tool for that and adding it to your HTML header is the simplest way to get started.
Notice, that we want to remove <pre> from the the list of skipped tags, as default HTML renderer will wrap raw and markdown cells in a <pre> tag.
<html>
<head>
<script>
MathJax = {
options: {
skipHtmlTags: [ // includes "pre" by default
"script",
"noscript",
"style",
"textarea",
"code",
"annotation",
"annotation-xml"
],
}
};
</script>
</head>
</html>
MathJax is very configurable and you can read more about that here.
You may also find the official MathJax config used in the Jupyter project useful.
License
This software is released under the MIT License.
Documentation
ΒΆ
Index ΒΆ
Constants ΒΆ
This section is empty.
Variables ΒΆ
This section is empty.
Functions ΒΆ
func DefaultRenderer ΒΆ
DefaultRenderer configures an HTML renderer.
Types ΒΆ
type Extension ΒΆ added in v0.2.0
type Extension interface {
Extend(n *Notebook)
}
Extension adds new capabilities to the base Notebook.
type Notebook ΒΆ
type Notebook struct {
// contains filtered or unexported fields
}
Notebook is an extensible Converter implementation.
type Option ΒΆ
type Option func(*Notebook)
func WithExtensions ΒΆ added in v0.2.0
WithExtensions adds extensions.
func WithRenderOptions ΒΆ
WithRendererOptions adds configuration to the current notebook renderer.
func WithRenderer ΒΆ
WithRenderer sets a new notebook renderer. Set this option before passing any WithRenderOptions.
Source Files
Directories
ΒΆ
| Path | Synopsis |
|---|---|
|
example
|
|
|
nbee
Module
|
|
|
adapter
Package adapter provides convenient adapters for other popular packages making it simple to use those as nb extensions.
|
Package adapter provides convenient adapters for other popular packages making it simple to use those as nb extensions. |
|
extra/goldmark-jupyter
Module
|
|
|
pkg
|
|
|
test
Package test provides test doubles that implement some of nb interfaces.
|
Package test provides test doubles that implement some of nb interfaces. |
|
internal/wildcard
Package wildcard implements simple pattern matching for strings with wildcard characters.
|
Package wildcard implements simple pattern matching for strings with wildcard characters. |
|
Package schema defines the common data format for elements of a Jupyter notebook.
|
Package schema defines the common data format for elements of a Jupyter notebook. |
|
v3
Package v3 provides a decoder for Jupyter Notebooks v1.0, v2.0, and v3.0.
|
Package v3 provides a decoder for Jupyter Notebooks v1.0, v2.0, and v3.0. |
|
v4
Package v4 provides a decoder for Jupyter Notebooks v4.0 and later minor versions.
|
Package v4 provides a decoder for Jupyter Notebooks v4.0 and later minor versions. |