assets

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 14 Imported by: 0

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

View Source
const HashLen = 10

HashLen is the number of hex digits of the SHA-256 kept in a file name.

View Source
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

func Command

func Command() cli.Command

Command is the "assets" subcommand.

func Strip

func Strip(src string, blocks []Block) string

Strip returns src without the blocks. A block that sat alone on its line takes the whole line with it, so the template does not keep a blank gap.

func Under

func Under(parent cli.Command) cli.Command

Under returns parent with the subcommand "assets" added: "ypy gen assets" runs this tool and every other argument goes to parent unchanged.

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

func Scan(src string, actions bool) ([]Block, error)

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

type Entry struct {
	CSS string `json:"css,omitempty"`
	JS  string `json:"js,omitempty"`
}

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 Group

type Group string

Group says what one output file is made from.

const (
	ByPackage  Group = "package"
	ByTemplate Group = "template"
)

The two groupings. A package is a directory: its templates and companion files give one stylesheet and one script. A template gives its own pair.

type Kind

type Kind string

Kind is the type of an asset.

const (
	CSS Kind = "css"
	JS  Kind = "js"
)

The two kinds of asset the tool extracts.

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.

func Plan

func Plan(o Options) (*Output, error)

Plan scans the directory and computes every output file. It does not write.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL