Documentation
¶
Overview ¶
Package export turns a built deck into images and documents without a browser: go-webengine lays each slide out and paints it, go-pdfkit writes the PDF. Marp CLI drives a headless Chrome for the same outputs.
The slides are rendered in the box frame (deck.FrameBox), which needs neither <foreignObject> nor generated content from the layout engine. The writers take the deck as a *doc.Doc (slides.Build.Doc), so that this package carries no renderer: a host may build the deck in one place and export it in another.
Index ¶
- Variables
- func DefaultWorkers() int
- func Each(ctx context.Context, b *doc.Doc, opts Options, ...) error
- func EachEncoded(ctx context.Context, b *doc.Doc, opts Options, format string, ...) error
- func EachLayout(ctx context.Context, b *doc.Doc, opts Options, ...) error
- func FontData(name string) []byte
- func FontNames() []string
- func JPEG(w io.Writer, img image.Image, opts Options) error
- func ODP(w io.Writer, b *doc.Doc, images []*image.RGBA) error
- func PDF(w io.Writer, b *doc.Doc, images []*image.RGBA) error
- func PNG(w io.Writer, img image.Image) error
- func PPTX(w io.Writer, b *doc.Doc, images []*image.RGBA) error
- func Rasterize(ctx context.Context, b *doc.Doc, opts Options) ([]*image.RGBA, error)
- func SetFontSource(src func(name string) ([]byte, error))
- func VectorPDF(ctx context.Context, w io.Writer, b *doc.Doc, opts Options) error
- type ODPWriter
- type Options
- type PDFOptions
- type PDFWriter
- type PPTXWriter
Constants ¶
This section is empty.
Variables ¶
var DefaultPDFOptions = PDFOptions{OutlinePages: true, OutlineHeadings: true}
DefaultPDFOptions are what NewPDF uses: no notes, and the whole outline. marp-cli writes no outline unless --pdf-outlines is given; go-slides has written one since its first PDF, and keeps doing it.
Functions ¶
func DefaultWorkers ¶ added in v0.3.0
func DefaultWorkers() int
DefaultWorkers is how many slides Each renders at once by default: the number of CPUs Go may use, at most 4. The slides are independent, so more workers render a deck faster; each holds one slide's layout and image, so more workers also hold more memory. Measured on 10 slides (BENCHMARKS.md): 1 → 2 workers saves 47 % of the time, 2 → 4 another 27 %, 4 → 8 only 21 % for 15 % more heap; 4 keeps the heap near one worker's.
func Each ¶ added in v0.3.0
func Each(ctx context.Context, b *doc.Doc, opts Options, emit func(i int, img *image.RGBA) error) error
Each renders every slide of b, which must have been rendered in deck.FrameBox, and calls emit with each image in slide order, from one goroutine. Up to opts.Workers slides are rendered concurrently, and no more images than that exist at once: a slide starts only when the image of the one that many places before it has been emitted. emit may keep the image. An error from a slide or from emit stops the render and is returned.
func EachEncoded ¶ added in v0.3.0
func EachEncoded(ctx context.Context, b *doc.Doc, opts Options, format string, emit func(i int, data []byte) error) error
EachEncoded is Each with every image encoded, as "png" or "jpeg", by the worker that rendered it, so that encoding runs in parallel too and only the encoded bytes wait for their turn.
func EachLayout ¶ added in v0.4.0
func EachLayout(ctx context.Context, b *doc.Doc, opts Options, emit func(i int, l *engine.PageLayout) error) error
EachLayout lays every slide of b out, as Each does, and calls emit with each layout in slide order, from one goroutine, unpainted: the caller paints it — as vectors, for a PDF (see PDFWriter.AddLayout). Up to opts.Workers slides are laid out concurrently, and no more layouts than that exist at once.
func FontData ¶ added in v0.11.0
FontData is the embedded file of one of FontNames, nil for another name: what a host that builds a slides_fontsext module serves, byte for byte.
func FontNames ¶ added in v0.11.0
func FontNames() []string
FontNames are the files of the fonts the exports bundle for Marp's built-in themes (Lato, Roboto Mono), named as go-opentype/fonts names them: "lato/lato-black.ttf". A host built with the slides_fontsext tag serves these and hands them over through SetFontSource.
func ODP ¶ added in v0.3.0
ODP writes an OpenDocument presentation through go-odf: each slide is a full-slide picture at the slide's size, with the slide's speaker notes, as PPTX does. Render at Scale 2 for a sharp deck.
func PDF ¶
PDF writes one page per slide, each drawn from its image (see PDFWriter.Add; VectorPDF draws them as vectors). A page is the slide's size, a CSS pixel being 3/4 of a point, as Chrome prints Marp's @page size. The outline lists each slide and, under it, its headings (marp --pdf-outlines).
func PPTX ¶ added in v0.2.0
PPTX writes a PowerPoint deck through go-ooxml: each slide is a full-slide picture, at the slide's size, with the slide's speaker notes, as marp-cli's --pptx does. The pictures are PNG; render them at Scale 2 for a sharp deck (marp-cli's default for PPTX).
func Rasterize ¶
Rasterize renders every slide of b, which must have been rendered in deck.FrameBox, to an image of the slide's size times opts.Scale. It holds every image at once; Each hands them over one at a time.
func SetFontSource ¶ added in v0.11.0
SetFontSource sets where the bundled theme fonts' files come from: src is asked for one of FontNames the first time a slide draws that face, once per process. A build with the slides_fontsext tag embeds none of them and must set it before the first export: a host in a browser fetches them from its own origin then, so that a deck that never draws Lato never downloads it. Without the tag the embedded files answer.
Types ¶
type ODPWriter ¶ added in v0.3.0
type ODPWriter struct {
// contains filtered or unexported fields
}
ODPWriter builds the deck ODP writes one slide at a time, from each slide's PNG (EachEncoded gives them), so that the deck is never held as images.
func NewODP ¶ added in v0.3.0
NewODP starts the OpenDocument deck of b. go-odf takes the size in CSS pixels.
type Options ¶
type Options struct {
// BaseURL resolves the deck's relative URLs (images, backgrounds):
// typically "file:///path/to/deck/dir/".
BaseURL string
// NoFonts leaves out the fonts bundled for the built-in themes.
NoFonts bool
// JPEGQuality is the JPEG quality, 1 to 100; 0 means 85, marp-cli's.
JPEGQuality int
// Scale is the number of device pixels per CSS pixel: 2 renders a
// 1280×720 slide as 2560×1440, text and vectors drawn at that density
// rather than enlarged. 0 means 1 (marp-cli's --image-scale).
Scale float64
// FileRoot, when set, lets the slides load file: URLs from under this
// directory and nowhere else; empty refuses every local file, as
// marp-cli does without --allow-local-files.
FileRoot string
// Workers is how many slides are rendered at once: 0 means
// DefaultWorkers(). It also bounds memory, since Each holds at most
// this many slide images at a time.
Workers int
// Fetcher, when set, fetches the slides' http(s) URLs (images,
// backgrounds, style sheets, fonts) instead of go-webengine's HTTP
// client (engine.Engine.Fetcher): a host whose platform fetches for it,
// such as a browser's fetch in a WebAssembly build without network.
Fetcher func(ctx context.Context, url string) (body []byte, contentType string, err error)
}
Options configures the export.
type PDFOptions ¶ added in v0.6.0
type PDFOptions struct {
// Notes adds each slide's speaker notes to its page as a text annotation
// (marp-cli --pdf-notes).
Notes bool
// OutlinePages adds a bookmark "Page N" for each slide, and
// OutlineHeadings one for each heading of the slide, nested by level
// under it (marp-cli --pdf-outlines.pages and .headings).
OutlinePages, OutlineHeadings bool
// Untagged writes the PDF without its logical structure. By default a
// PDF is tagged, as Chrome's and so marp-cli's are: a screen reader
// reads its headings, paragraphs, lists, tables, links, images and
// formulas in reading order, and the file declares PDF/UA-1, with the
// deck's title and language.
Untagged bool
// Lang is the language when the deck's lang directive gives none
// (--lang); with neither, a tagged PDF says "en", as it must say one.
Lang string
}
PDFOptions are what the PDF carries beyond its pages, marp-cli's --pdf-notes and --pdf-outlines.
type PDFWriter ¶ added in v0.3.0
type PDFWriter struct {
// Stats adds up what AddLayout drew as vectors and what it had to
// draw as bitmaps (paint.VectorStats).
Stats paint.VectorStats
// contains filtered or unexported fields
}
PDFWriter builds a PDF one slide at a time, so that a deck is never held whole: each page is drawn when it is added — from an image (Add) or from a layout, as vectors (AddLayout) — and what it was drawn from can be dropped.
func NewPDFWith ¶ added in v0.6.0
func NewPDFWith(b *doc.Doc, opts PDFOptions) *PDFWriter
NewPDFWith starts the PDF of b.
func (*PDFWriter) AddLayout ¶ added in v0.4.0
func (p *PDFWriter) AddLayout(l *engine.PageLayout) error
AddLayout adds the next slide's page, drawn from its layout as vectors: text as text in the fonts the slide was laid out with (subset-embedded, selectable and searchable), backgrounds, borders and gradients as paths and shadings, images placed once per document however many slides show them, and every link a clickable area. What has no vector form here — an element under opacity, a filter, a blurred shadow — is drawn as a bitmap of just that element (paint.PaintVector).
type PPTXWriter ¶ added in v0.3.0
type PPTXWriter struct {
// contains filtered or unexported fields
}
PPTXWriter builds the deck PPTX writes one slide at a time, from each slide's PNG (EachEncoded gives them), so that the deck is never held as images.
func NewPPTX ¶ added in v0.3.0
func NewPPTX(b *doc.Doc) *PPTXWriter
NewPPTX starts the PowerPoint deck of b.
func (*PPTXWriter) Add ¶ added in v0.3.0
func (w *PPTXWriter) Add(png []byte)
Add adds the next slide, its picture given as PNG bytes.
func (*PPTXWriter) AddLayout ¶ added in v0.5.0
func (w *PPTXWriter) AddLayout(l *engine.PageLayout) error
AddLayout adds the next slide as editable content: its text in text boxes set in the slide's own fonts (embedded), its backgrounds, borders and gradients as shapes, its pictures each stored once — drawn from the slide's layout, so at the positions of the image and PDF exports. What a slide cannot hold is a picture of that element (see officecanvas).