html

Documentation

Overview

Package html renders markdown to a complete, styled HTML document. Importing it (for side effects) registers the "html" format. Its Render function is also reused by the browser-based PDF fallback.

Local images referenced by the document are embedded as data URIs so the output is self-contained — it needs no accompanying asset files and survives being moved or imported elsewhere. Remote (http/https) images stay live references by default; with -flatten they are fetched and embedded too, for a fully self-contained document (at the cost of needing network access).

Fenced code blocks tagged `mermaid` are emitted as <pre class="mermaid"> elements and, when present, the document inlines the mermaid library so the diagrams render client-side (in a browser, or in the headless-browser PDF renderer).

Index

• Constants
• Variables
• func ChromaCSS(style string) string
• func DocumentTitle(src []byte) string
• func EnableDiagrams(names []string) error
• func FirstHeading(src []byte) string
• func MermaidStandalonePage(source []byte, theme string) []byte
• func Render(src []byte) ([]byte, error)
• func RenderD2(src []byte, dark bool) ([]byte, error)
• func RenderFrom(src []byte, baseDir string) ([]byte, error)
• func RenderPlantUML(src []byte, dark bool) ([]byte, error)
• func RequiresBrowser(src []byte) bool
• func RequiresMermaidWait(src []byte) bool
• func SupportedDiagrams() []string
• func XHTMLBody(src []byte) ([]byte, string, error)
• type Converter
  • func (Converter) Convert(src []byte, w io.Writer) error
  • func (Converter) ConvertFrom(src []byte, srcPath string, w io.Writer) error

Constants

const BaseCSS = `` /* 700-byte string literal not displayed */

BaseCSS is md2's built-in stylesheet (readable body, bordered tables, code blocks). It is embedded in the HTML document head and also reused by the EPUB converter, which writes it to a packaged stylesheet so ebooks share the same base look.

Variables

var (
	Title  string
	Author string
)

Title and Author are document metadata shared across output formats, set from the -title and -author CLI flags. They live here because html is the renderer every format depends on: the HTML <title>/<meta author>, the browser-rendered PDF's title, the pure-Go PDF's info dictionary, and the EPUB's dc:title/creator all derive from them. An empty Title falls back to the document's first heading (see DocumentTitle); an empty Author omits author metadata.

var ExtraCSS string

ExtraCSS, when non-empty, is appended as an additional <style> block just before </head>, after the built-in stylesheet, so it can override or extend the defaults using normal CSS cascade rules — it never replaces the built-in styling. Applies to HTML output and the browser-rendered PDF fallback (both render through RenderFrom); NOT the pure-Go PDF path, which has no HTML/CSS layer. Set from the -css CLI flag.

var Flatten bool

Flatten controls how enabled diagrams are emitted. When false (default), a diagram becomes a <pre class="mermaid"> with the mermaid library inlined, so it renders client-side in a browser — interactive, but needing a JS runtime to view. When true, the document is rendered in a headless browser and each diagram is replaced by a static <img> (a PNG), producing a fully portable file that displays anywhere (e.g. imported into Google Docs). Set from the -flatten CLI flag.

var KeepDiagramSource bool

KeepDiagramSource, when true, keeps the original fenced diagram source in the output in addition to the rendered diagram — the rendered diagram is emitted first, immediately followed by the source as a normal code block. Off by default (a diagram replaces its source). Set from the -keep-diagram-source flag.

var PlantUMLServer = "https://www.plantuml.com/plantuml"

PlantUMLServer is the base URL of the PlantUML server used to render `plantuml` diagrams to SVG at build time. PlantUML has no pure-Go or client-side renderer, so — unlike d2 (compiled in-process) — md2 must encode the diagram source and fetch the rendered SVG from a server, then inline it so the output stays self-contained. Defaults to the public plantuml.com server; set from the -plantuml-server CLI flag (e.g. a self-hosted server for offline or private use). Note that rendering sends the diagram source to this server.

var Rasterizer func(doc []byte) ([]byte, error)

Rasterizer, if set, flattens a diagram-bearing HTML document to one with static <img> diagrams using a headless browser. The chrome package installs it via init; html does not import chrome (which imports html) so as to avoid an import cycle, hence this indirection.

var RemoteUserAgent = "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 " +
	"(KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36"

RemoteUserAgent is the User-Agent sent when -flatten fetches remote images to embed. Browser-like by default because some hosts (CDNs, Wikipedia, etc.) 403 the default Go client UA; overridable via the -user-agent CLI flag.

Functions

func ChromaCSS

func ChromaCSS(style string) string

ChromaCSS returns the syntax-highlight stylesheet for the named chroma style (e.g. "github-dark"), for callers that need a variant beyond the default the document uses — the EPUB converter uses it for a prefers-color-scheme:dark block. Token class names are the same across styles, so a dark variant scoped in a dark media query cleanly overrides the light one.

func DocumentTitle

func DocumentTitle(src []byte) string

DocumentTitle returns Title, or the document's first heading when Title is unset (may be ""). Shared by every output format's title metadata.

func EnableDiagrams

func EnableDiagrams(names []string) error

EnableDiagrams turns on rendering for the named diagram languages. The special name "all" enables every supported renderer. An unknown name returns an error and leaves the enabled set unchanged.

func FirstHeading

func FirstHeading(src []byte) string

FirstHeading returns the plain text of the document's first heading, or "" if there is none.

func MermaidStandalonePage

func MermaidStandalonePage(source []byte, theme string) []byte

MermaidStandalonePage returns a minimal HTML document rendering a single mermaid diagram client-side, for the EPUB converter to load in a headless browser and extract the rendered SVG (an ebook reader has no JS runtime, so mermaid is pre-rendered). htmlLabels:false makes mermaid emit SVG <text> labels rather than <foreignObject> HTML, so the extracted SVG is well-formed XML that inlines into the XHTML chapter. The init script signals completion via window.__md2MermaidDone, which the caller waits on — the same contract as the inlined HTML/PDF path.

func Render

func Render(src []byte) ([]byte, error)

Render converts markdown into a full HTML document, resolving relative image references against the current working directory. See RenderFrom.

func RenderD2

func RenderD2(src []byte, dark bool) ([]byte, error)

RenderD2 compiles a d2 diagram's source into a standalone SVG element. dark selects d2's "Dark Mauve" theme (for a dark-mode variant); otherwise the neutral default. Exposed for the EPUB converter, which renders a light and a dark variant of each diagram.

func RenderFrom

func RenderFrom(src []byte, baseDir string) ([]byte, error)

RenderFrom converts markdown into a full, self-contained HTML document with basic styling (readable body, bordered tables, code blocks). Local images referenced by the document are embedded as data URIs — relative paths are resolved against baseDir — so the output stands alone without its asset files. When mermaid rendering is enabled and the source contains mermaid diagrams, the mermaid library and an init script are inlined so the diagrams render without any network access.

func RenderPlantUML

func RenderPlantUML(src []byte, dark bool) ([]byte, error)

RenderPlantUML renders a plantuml diagram to SVG. dark injects skinparams for a dark-mode variant. Exposed for the EPUB converter, which renders a light and a dark variant of each diagram.

func RequiresBrowser

func RequiresBrowser(src []byte) bool

RequiresBrowser reports whether rendering the source to PDF needs the headless browser rather than the pure-Go renderer (goldmark-pdf), because it contains an enabled diagram the pure-Go path cannot produce: mermaid needs a client-side JS runtime, and d2 renders to inline SVG that gofpdf cannot rasterize. Either way the browser draws it faithfully. The PDF renderer uses this to choose its path; -flatten uses it to decide a document needs the rasterizer.

func RequiresMermaidWait

func RequiresMermaidWait(src []byte) bool

RequiresMermaidWait reports whether the source contains an enabled mermaid diagram, which the browser must draw asynchronously (via the inlined mermaid script) before the PDF is printed. It is distinct from RequiresBrowser: a d2 diagram routes through the browser too, but its SVG is already in the DOM at load, so there is nothing to wait for.

func SupportedDiagrams

func SupportedDiagrams() []string

SupportedDiagrams returns the diagram languages that can be enabled, sorted.

func XHTMLBody

func XHTMLBody(src []byte) ([]byte, string, error)

XHTMLBody renders markdown to a well-formed XHTML body fragment plus the chroma stylesheet for any highlighted code, for the EPUB converter. Unlike RenderFrom it does not wrap the result in a full document and does not inline images — the caller packages them into the archive. Enabled diagrams are left as <pre class="lang">source</pre> (asSource mode) rather than rendered, so the EPUB converter can render a light and a dark variant of each and toggle them by the reader's color scheme.

Types

type Converter

type Converter struct{}

Converter renders markdown source to an HTML document.

func (Converter) Convert

func (Converter) Convert(src []byte, w io.Writer) error

func (Converter) ConvertFrom

func (Converter) ConvertFrom(src []byte, srcPath string, w io.Writer) error

ConvertFrom is Convert with the input file path provided, so relative image references can be resolved against its directory and embedded.