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.
Although the current release only supports v4.4 notebooks, support for other formats will be added soon (see the Roadmap).
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)
Without extensions or CSS the output may look rather bland and messy. The package comes with the Jupyter's classic light theme, and you can capture it by creating a new html.Renderer with a WithCSSWriter option:
// 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 er != nil {
panic(err)
}
// Create the final output (could be a file)
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>")
Finally, starting with v0.2.0 you will be able to choose from a number of extensions to create neater notebooks.
Roadmap πΊ
- v0.2.0:
- Extension API + several extension packages (will be published separately)
- Support for cell attachments in markdown cells
- Better granularity in the cell renderer registry API
- v0.3.0:
- Support for older
nbformatversions:v4.*v3.0v2.0
- Custom CSS
- Custom class prefix / class names
- Custom CSS with Go templates
- Support for older
- v0.4.0:
- Support for
v1.0notebooks - Built-in pretty-printing for JSON outputs
- Support for
- 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 Notebook ΒΆ
type Notebook struct {
// contains filtered or unexported fields
}
Notebook is an extensible Converter implementation.
type Option ΒΆ
type Option func(*Notebook)
func WithRenderOptions ΒΆ
WithRendererOptions adds configuration to the notebook renderer.
func WithRenderer ΒΆ
WithRenderer sets a new notebook renderer. This option should be supplied before passing any WithRenderOptions.
Source Files
Directories