Documentation
¶
Overview ¶
Package assets implements "ypy gen assets": it takes the CSS and the small scripts an author writes next to a template and extracts them into files whose names carry a hash of their content, so the page that results has nothing inline and passes a strict Content-Security-Policy.
Where the author writes ¶
In a template (.html, .gohtml, .templ or .kyse.go) a <style ypy-asset> or a <script ypy-asset> element is an asset of that template. Next to a template a file name.ypy.css or name.ypy.js is the same thing without the markup.
Grouping ¶
The default is one stylesheet and one script per package, a package being a directory. A component library is written and shipped by directory, a page asks for the pieces it uses with one name each, and a change in one template invalidates the cache of its neighbours only. The alternative, one pair per template, is --group template; it suits a site whose pages share almost nothing.
Output ¶
<name>.<hash>.css and <name>.<hash>.js, where hash is the first HashLen hex digits of the SHA-256 of the file, and manifest.json:
{"ui/cards": {"css": "ui-cards.1a2b3c4d5e.css", "js": "ui-cards.9f8e7d6c5b.js"}}
The paths in the manifest are relative to its directory. Nothing in the output depends on the time, the machine or the order of a directory listing, so a run on the same input writes the same bytes, and --check can compare.
The Go SDK reads the manifest (ypy.LoadManifest) and writes the <link> and <script> tags with integrity and the nonce of the page.
Index ¶
Constants ¶
const HashLen = 10
HashLen is the number of hex digits of the SHA-256 kept in a file name.
const Marker = "ypy-asset"
Marker is the attribute that makes a <style> or <script> element an asset of the template that holds it.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Block ¶
type Block struct {
Kind Kind // css or js
Content string // what sits between the tags, newlines normalised to \n
Line int // 1-based line of the opening tag
// Start and End delimit the whole element in the source: the opening tag
// through the closing tag.
Start, End int
}
Block is one marked element found in a template.
func Scan ¶
Scan finds the marked <style> and <script> elements of one template. It is a small scanner and not an HTML parser: it knows quoted attribute values and the raw text of the two elements, which is all a marked block needs.
A marked block has to be extractable as it is, so Scan reports an error, with the line, when it is not: a <style> with a media attribute, a <script> that is a module or carries a type other than JavaScript, a block with no closing tag, and (when actions is true) a block that holds a template action.
type Entry ¶
Entry is one origin in the manifest: the files that hold its CSS and its script, as paths relative to the directory of the manifest. Either may be empty.
type Options ¶
type Options struct {
Dir string // the directory scanned
Out string // where the hashed files go
Manifest string // the manifest file; empty means Out/manifest.json
StripOut string // when set, copies of the templates without the blocks go here
Group Group // empty means ByPackage
}
Options says what to read and what to write. The paths are absolute.
type Output ¶
type Output struct {
// Files maps an absolute path to its content.
Files map[string][]byte
// Manifest is the manifest, by origin.
Manifest map[string]Entry
// ManifestPath is where the manifest goes.
ManifestPath string
// Counts, for the report.
CSS, JS, Templates int
}
Output is everything a run produces, without having written any of it.