favicon

type CompareFunc ¶

type CompareFunc func(a, b *Icon) int

CompareFunc compares Icons for sorting. Set a Finder's compare by passing WithCompareFunc(...) to New().

type Filter ¶

type Filter func(*Icon) *Icon

Filter accepts/rejects/modifies Icons. If if returns nil, the Icon is ignored. Set a Finder's filters by passing WithFilter(...) to New().

type Finder ¶

type Finder struct {
	// contains filtered or unexported fields
}

Finder discovers favicons for a URL. By default, a Finder looks in the following places:

The HTML page at the given URL for...

• icons in <link> tags
• Open Graph images
• Twitter images

The manifest file...

• defined in the HTML page
• or...
• /manifest.json

Standard favicon paths

• /favicon.ico
• /apple-touch-icon.png

Pass the IgnoreManifest and/or IgnoreWellKnown Options to New() to reduce the number of requests made to webservers.

func New(option ...Option) *Finder

// Find icons defined in HTML, the manifest file and at default locations
icons, err := favicon.Find("https://www.deanishe.net")
if err != nil {
	panic(err)
}
// icons are sorted widest first
for _, i := range icons {
	fmt.Printf("%dx%d\t%s\n", i.Width, i.Height, i.FileExt)
}

Output:

256x256	png
192x192	png
180x180	png
32x32	png
16x16	png
0x0	png
0x0	ico

f := favicon.New(
	// Don't look for or parse a manifest.json file
	favicon.IgnoreManifest,
	// Don't request files like /favicon.ico to see if they exist
	favicon.IgnoreWellKnown,
)
// Find icons defined in HTML, the manifest file and at default locations
icons, err := f.Find("https://www.deanishe.net")
if err != nil {
	panic(err)
}
// icons are sorted widest first
for _, i := range icons {
	fmt.Printf("%dx%d\t%s\n", i.Width, i.Height, i.MimeType)
}

Output:

180x180	image/png
32x32	image/png
16x16	image/png

func (f *Finder) Find(url string) ([]*Icon, error)

func (f *Finder) FindGoQueryDocument(doc *gq.Document, baseURL ...string) ([]*Icon, error)

func (f *Finder) FindNode(n *html.Node, baseURL ...string) ([]*Icon, error)

func (f *Finder) FindReader(r io.Reader, baseURL ...string) ([]*Icon, error)

type Icon ¶

type Icon struct {
	URL      string `json:"url"`       // Never empty
	MimeType string `json:"mimetype"`  // MIME type of icon; never empty
	FileExt  string `json:"extension"` // File extension; may be empty
	// Dimensions are extracted from markup/manifest, falling back to
	// searching for numbers in the URL.
	Width  int `json:"width"`
	Height int `json:"height"`
	// Hash of URL and dimensions to uniquely identify icon.
	Hash string `json:"hash"`
}

Icon is a favicon parsed from an HTML file or JSON manifest.

TODO: Use *Icon everywhere to be consistent with higher-level APIs that return nil for "not found".

func Find(url string) ([]*Icon, error)

func FindGoQueryDocument(doc *gq.Document, baseURL ...string) ([]*Icon, error)

func FindNode(n *html.Node, baseURL ...string) ([]*Icon, error)

func FindReader(r io.Reader, baseURL ...string) ([]*Icon, error)

func (i Icon) Copy() *Icon

func (i Icon) IsSquare() bool

func (i Icon) String() string

type Logger ¶

type Logger interface {
	Printf(string, ...any)
}

Logger describes the logger used by Finder.

type Manifest ¶

type Manifest struct {
	Icons []ManifestIcon `json:"icons"`
}

Manifest is the relevant parts of a manifest.json file.

type ManifestIcon ¶

type ManifestIcon struct {
	URL      string `json:"src"`
	Type     string `json:"type"`
	RawSizes string `json:"sizes"`
}

ManifestIcon is an icon from a manifest.json file.

type Option ¶

type Option func(*Finder)

Option configures Finder. Pass Options to New().

var (
	// IgnoreWellKnown ignores common locations like /favicon.ico.
	IgnoreWellKnown Option = func(f *Finder) { f.ignoreWellKnown = true }

	// IgnoreManifest ignores manifest.json files.
	IgnoreManifest Option = func(f *Finder) { f.ignoreManifest = true }

	// IgnoreNoSize ignores icons with no specified size.
	IgnoreNoSize Option = WithFilter(func(icon *Icon) *Icon {
		if icon.Width == 0 || icon.Height == 0 {
			return nil
		}
		return icon
	})

	// OnlyPNG ignores non-PNG files.
	OnlyPNG Option = OnlyMimeType("image/png")

	// OnlyICO ignores non-ICO files.
	OnlyICO Option = WithFilter(func(icon *Icon) *Icon {
		if icon.MimeType == "image/x-icon" || icon.MimeType == "image/vnd.microsoft.icon" {
			return icon
		}
		return nil
	})

	// OnlySquare ignores non-square files. NOTE: Icons without a known size are also returned.
	OnlySquare Option = WithFilter(func(icon *Icon) *Icon {
		if !icon.IsSquare() {
			return nil
		}
		return icon
	})

	// SortByWidth sorts icons by width (largest first), and then by image type
	// (PNG > JPEG > SVG > ICO).
	// This is default sort logic.
	SortByWidth Option = WithCompareFunc(func(a, b *Icon) int {
		return defaultCompareFunc(a, b)
	})

	// NopSort represents a no operation sorting.
	NopSort Option = WithCompareFunc(nil)
)

func MaxHeight(height int) Option

func MaxWidth(width int) Option

func MinHeight(height int) Option

func MinWidth(width int) Option

func OnlyMimeType(mimeType ...string) Option

func WithClient(client *http.Client) Option

func WithCompareFunc(compare CompareFunc) Option

func WithFilter(filter ...Filter) Option

func WithLogger(logger Logger) Option