Input Sources
There are two constructors. NewDocumentFromString takes HTML markup you already
have in memory. NewDocument takes a path and works out what it is:
doc, err := unihtml.NewDocument(path)The dispatch is by inspection, in this order. If path parses as a URL with an
http or https scheme, the server fetches it. Otherwise the path is stat’ed: a
directory is zipped in memory and uploaded whole, and anything else is read as a
single HTML file. A path that does not exist returns the os.Stat error, so a typo
surfaces as no such file or directory rather than as an empty PDF.
That means the choice of input kind is made by what you pass, not by a flag, and there is no way to override it.
What travels to the server
| Input | Sent as | Assets resolved by |
|---|---|---|
String, NewDocumentFromString | The markup, text/html | Nothing. Absolute URLs only. |
File, NewDocument("page.html") | The file’s bytes, text/html | Nothing. Relative paths will not resolve. |
Directory, NewDocument("data") | A zip of the tree, application/zip | Paths relative to the zip root. |
URL, NewDocument("https://...") | The URL as text | The remote site, as a browser would. |
File against directory is the distinction to get right. A single HTML file is uploaded
on its own, so its <link href="css/style.css"> and <img src="images/frog.jpg"> have
nothing to resolve against on the server and the stylesheet and image are missing from
the render. No error either way. The moment your page references a local asset, you want
the directory form.
Strings and single files suit self-contained markup: inline styles, a <style> block,
or assets on absolute https URLs. Anything external is fetched by the container, so it
needs outbound access for a webfont or a CDN script to load.
Where to look
| Guide | Covers |
|---|---|
| Inline HTML | Building a document from a Go string, and when a template is the better shape. |
| HTML File | Converting a file from disk, and why relative asset paths do not resolve. |
| Asset Directory | Sending HTML with its CSS, images and scripts, and how the zip is laid out. |
| Web URL | Rendering a live page, and the timeouts and failure modes that come with it. |
Whichever you pick, the document you get back behaves identically from then on. Page setup and the choice of output path are the same for all four.