export

README

core/export

Renders a Markdown document as a standalone HTML page or as plain text, and draws one Mermaid diagram as a page of its own, for an export and for a preview. A page's colours are a shipped theme's, its Content-Security-Policy allows no network access, and a ```mermaid block is drawn in the page by the vendored mermaid.js (core/export/mermaid), admitted by its digest. A page without a diagram has no script.

Name	What
Format	an output format: HTML ("html") or Text ("text")
Options	what a render reads besides the source: Base, the directory relative links are resolved from (each becomes a file: URL; "" keeps links as written); SourceSpans, which puts each block's source byte range on it (data-src); Document, the source's file, whose embeds are drawn (below); and TableRows and TableWidth, which fit its tables to a narrower view
Render(source, format, theme)	RenderWith with no options
RenderWith(source, format, theme, options)	the page or text; an unknown theme (for HTML) or format is an error
DiagramPage(source, theme)	a page of one Mermaid diagram at its own size on the theme's background
Themes()	the theme names, sorted: dark, light, mono, retro, sepia
ThemeOf(tuiTheme)	the export theme for a TUI theme: its own where there is one, else dark
Background(theme)	a theme's page colour; dark's for an unknown theme

HTML shows an image as its alt text, unless Options.Document names the source's file. Then an embed, ![alt](path), of a file beside the document is drawn, as xmd draws it:

• a Mermaid diagram (.mmd) as a diagram;
• a table (.csv) as a table, with its first row as the header. It shows 1000 rows, 64 columns and 20,000 cells at most, then says how many rows and columns are not shown. Options.TableRows and Options.TableWidth fit it to a narrower view: that many rows, and the first columns that fit in that many characters (one at least);
• an image (.png, .jpg, .gif, .svg, .webp, .avif, .bmp) as the image, written in as a data: URI, so the page stays whole.

The path is looked for beside the document, then in its resources folder (its name without .x.md or .md: plan.x.md's is plan/), and nowhere else. A path out of the document's folder, an absolute path, a URL and a symlink pointing out are not followed.

A diagram or a table is drawn when it is its paragraph's only content. A file that is missing, too large (1 MiB for a diagram or table, 6 MiB for an image, 32 MiB of images per page) or of another kind is shown as its alt text.

Text drops frontmatter, link reference definitions and raw HTML, keeps code blocks as written, and ignores the theme.

Every function is safe for concurrent use: shared state is read-only or built once under a sync.Once. The only disk reads are Options.Document's embeds, inside its folder; RenderWith reads the working directory when Options.Base or Options.Document is relative.

Documentation

Overview

Package export renders a Markdown document as a standalone HTML page or as plain text, and draws a single Mermaid diagram as a page of its own, for an export and for a preview.

An HTML page is whole: its colours are one of the shipped themes' (Themes, ThemeOf, Background), its Content-Security-Policy allows no network access, and an image is shown as its alt text, unless Options.Document names the source's file: then an embed of a file beside it (a Mermaid diagram, a CSV table, an image) is drawn in the page (embed.go), an image as a data: URI. A ```mermaid block is drawn in the page by the vendored mermaid.js (core/export/mermaid); the page then holds that script, and its policy admits it and the one that starts it by their digests. A page without a diagram has no script. Options.Base makes the source's relative links file: URLs of the files they name, so the page's links reach them wherever it is written. Plain text drops frontmatter, link reference definitions and raw HTML, and keeps code blocks as written.

Concurrency: every exported function may be called from any number of goroutines. Each call parses its own tree from the source and does not change the source; the package's shared state is read-only after init (the themes, the mermaid regexp) or built once under a sync.Once (the vendored script and its digest). The package reads the disk only for Options.Document's embeds, inside the document's folder; RenderWith reads the process's working directory when Options.Base or Options.Document is relative.

Index

• func Background(theme string) string
• func CSVMarkdown(data []byte, rows int) (string, bool)
• func DiagramPage(source, theme string) ([]byte, error)
• func EmbedDiagram(doc, dest string) (string, bool)
• func EmbedMarkdown(doc, dest string, rows int) (string, bool)
• func Render(source []byte, format Format, theme string) ([]byte, error)
• func RenderWith(source []byte, format Format, theme string, options Options) ([]byte, error)
• func ThemeOf(tuiTheme string) string
• func Themes() []string
• type EmbedLine
  • func EmbedLines(source []byte) []EmbedLine
• type Format
• type Options

Functions

func Background

func Background(theme string) string

Background is a theme's page colour; dark's for a theme it does not have.

func CSVMarkdown

func CSVMarkdown(data []byte, rows int) (string, bool)

CSVMarkdown is CSV (a file's, or a csv fence's) as the Rendered view draws it: a Markdown table of literal cells, its first row the header, of at most rows rows (0: maxTableRows), and a last row saying what is not shown. ok is false for no rows, or what is not CSV.

func DiagramPage

func DiagramPage(source, theme string) ([]byte, error)

DiagramPage is a page of one Mermaid diagram, drawn at its own size on the theme's background: for a preview, which renders it whole and scrolls it.

func EmbedDiagram

func EmbedDiagram(doc, dest string) (string, bool)

EmbedDiagram is the Mermaid source of an embed of dest (.mmd) in the document at doc, read as the page reads it: beside the document, then in its resources folder, never out of its folder. ok is false for any other embed, and for a file that is missing, refused or too large.

func EmbedMarkdown

func EmbedMarkdown(doc, dest string, rows int) (string, bool)

EmbedMarkdown is the Markdown an editor's Rendered view draws in place of a line that embeds dest in the document at doc, read as the page reads it (beside the document, then in its resources folder, never out of its folder): a Mermaid diagram (.mmd) as a mermaid fence, a Vega-Lite chart (.chart.json) as a vega-lite fence, a table (.csv) as a Markdown table of at most rows rows (0: maxTableRows). ok is false for any other embed, and for a file that is missing, refused, too large or not CSV: the line stays as written.

func Render

func Render(source []byte, format Format, theme string) ([]byte, error)

Render is RenderWith without options: every link as the source has it.

func RenderWith

func RenderWith(source []byte, format Format, theme string, options Options) ([]byte, error)

RenderWith renders the Markdown source as format. HTML is a whole page in the named theme (one of Themes), its Mermaid diagrams drawn by the page's own script; theme is ignored for Text.

func ThemeOf

func ThemeOf(tuiTheme string) string

ThemeOf is the export theme for a TUI theme: its own where it has one, else dark.

func Themes

func Themes() []string

Themes are the themes an export takes, sorted.

Types

type EmbedLine

type EmbedLine struct {
	Line     int
	Dest     string
	Alone    bool
	From, To int
}

EmbedLine is a source line that holds an image and nothing else, as Markdown is parsed for the page (kind.ParseMarkdown): an editor draws Dest in the line's place when the image is Alone, its paragraph's only content, as the page draws a diagram or a table. From and To are the lines of the paragraph (or setext heading) it is in, whose shape decides whether it is alone.

Only an inline image () is Alone: an editor keeps a line's layout while the lines around it are unchanged, and a reference's (![t][ref]) destination is its definition's, which may be anywhere in the source. The page draws it all the same.

func EmbedLines

func EmbedLines(source []byte) []EmbedLine

EmbedLines are source's lines that hold only an image, in order.

type Format

type Format string

Format is what a Markdown source is rendered as.

const (
	HTML Format = "html"
	Text Format = "text"
)

The formats: a standalone HTML page in a theme, or plain text.

type Options

type Options struct {
	// Base is the directory the source's relative links are read from: each becomes the file: URL
	// of the file it names there, so the page's links reach their files wherever it is written. ""
	// writes every link as the source has it.
	Base string
	// SourceSpans puts each block element's source bytes on it (data-src="start-end"), for a
	// view that follows the editor: the GUI's native HTML preview scrolls to the cursor's block.
	SourceSpans bool
	// Document is the source's own file on disk. Its embeds (![alt](path)) of a Mermaid diagram
	// (.mmd), a Vega-Lite chart (.chart.json), a table (.csv) or an image are read beside it, or in
	// its resources folder, and drawn in the page (embed.go). "" draws each as its alt text.
	Document string
	// TableRows is how many rows an embedded table, or a csv fence's, shows (0: 1000); TableWidth
	// is the width, in characters, its columns are fit in: those that fit are shown, and the table
	// says how many are not (0: any width, 64 columns at most). For a view narrower than a
	// browser: the GUI's Rendered view of a note.
	TableRows, TableWidth int
}

Options are what a render reads besides the source, its format and its theme.