jupyter

README

goldmark-jupyter

From nbformat documentation:

Markdown (and raw) cells can have a number of attachments, typically inline images, that can be referenced in the markdown content of a cell. 🖇

(punctuation mine)

goldmark-jupyter helps goldmark recognise cell attachments and include them in the rendered markdown correctly.

goldmark	goldmark-jupyter

Installation

go get github.com/bevzzz/nb/extensions/extra/goldmark-jupyter

Usage

Package goldmark-jupyter exports 2 dedicated extensions for goldmark and nb, which should be used together like so:

import (
	"github.com/bevzzz/nb"
	"github.com/bevzzz/nb/extensions/extra/goldmark-jupyter"
	"github.com/yuin/goldmark"
)

md := goldmark.New(
	goldmark.WithExtensions(
		jupyter.Attachments(),
	),
)

c := nb.New(
	nb.WithExtensions(
		jupyter.Goldmark(md),
	),
)

if err := c.Convert(io.Stdout, b); err != nil {
	panic(err)
}

Attachments will extend the default goldmark.Markdown with a custom link parser and an image renderer. Quite naturally, this renderer accepts html.Options which can be passed to the constructor:

import (
	"github.com/bevzzz/nb/extensions/extra/goldmark-jupyter"
	"github.com/yuin/goldmark"
	"github.com/yuin/goldmark/render/html"
)

md := goldmark.New(
	goldmark.WithExtensions(
		jupyter.Attachments(
			html.WithXHTML(),
			html.WithUnsafe(),
		),
	),
)

Note, however, that options not applicable to image rendering will have no effect. As of the day of writing, goldmark v1.6.0 references these options when rendering images:

• WithXHML()
• WithUnsafe()
• WithWriter(w)

Contributing

Thank you for giving goldmark-jupyter a run!

If you find a bug that needs fixing or a feature that needs adding, please consider describing it in an issue or opening a PR.

License

This software is released under the MIT License.

Documentation

Overview

Package jupyter provides extensions for goldmark and nb. Together they add support for inline images, which have their data stored as cell attachments, in markdown cells.

How it is achieved:

1. Goldmark extends nb with a custom "markdown" cell renderer which stores cell attachments to the parser.Context on every render.

2. Attachments extends goldmark with a custom link parser (ast.KindLink) and an image NodeRenderFunc.

   The parser is context-aware and will get the related mime-bundle from the context and store it to node attributes for every link whose destination looks like "attachments:image.png"

   Custom image renderer writes base64-encoded data from the mime-bundle if one's present, falling back to the destination URL.

Index

• func Attachments(opts ...html.Option) goldmark.Extender
• func Goldmark(md goldmark.Markdown) nb.Extension

Functions

func Attachments

func Attachments(opts ...html.Option) goldmark.Extender

Attachments adds support for Jupyter cell attachments to goldmark parser and renderer.

func Goldmark

func Goldmark(md goldmark.Markdown) nb.Extension

Goldmark overrides the default rendering function for markdown cells and stores cell attachments to the parser.Context on every render.