validate

README

validate

The codeberg.org/derat/validate Go package validates:

• HTML documents using the W3C's online "Nu Html Checker"
• CSS using the W3C's online CSS Validation Service
• AMP HTML documents using a local installation of the amphtml-validator Node.js program

Supplied documents are uploaded (in the case of online validators) and any issues identified by the validator are parsed and returned.

Usage

import (
	"codeberg.org/derat/validate"
)
// ...
	f, err := os.Open("page.html")
	if err != nil {
		// ...
	}
	defer f.Close()

	// See also validate.AMP() and validate.CSS().
	issues, out, err := validate.HTML(context.Background(), f)
	if err != nil {
		// ...
	}

	// Iterate over the parsed issues.
	for _, is := range issues {
		fmt.Println(is)
	}
	// Display the full results page in a browser.
	if err := validate.LaunchBrowser(out); err != nil {
		// ...
	}

A command-line program named validate_page that validates a file or a document provided over stdin is also provided:

% go install codeberg.org/derat/validate/cmd/validate_page
% validate_page -browser page.html
% validate_page -type=amp index.amp.html
% validate_page <style.css
% validate_page -type=htmlcss -browser page.html  # check CSS in HTML doc

Documentation

Overview

Package validate validates HTML and related documents.

Index

• func AMPFiles(ctx context.Context, paths []string) (map[string][]Issue, error)
• func LaunchBrowser(page []byte) error
• type FileType
• type Issue
  • func AMP(ctx context.Context, r io.Reader) ([]Issue, error)
  • func CSS(ctx context.Context, r io.Reader, ft FileType) ([]Issue, []byte, error)
  • func HTML(ctx context.Context, r io.Reader) ([]Issue, []byte, error)
  • func (is Issue) String() string
• type Severity
  • func (s Severity) String() string

Functions

func AMPFiles

func AMPFiles(ctx context.Context, paths []string) (map[string][]Issue, error)

AMPFiles runs amphtml-validator to validate multiple AMP HTML files at the supplied paths. The returned map is keyed by the filenames from the paths argument.

AMPFiles may be much faster than AMP when validating multiple files, since the WebAssembly-based amphtml-validator can take a substantial amount of time to start: https://github.com/ampproject/amphtml/issues/37585.

func LaunchBrowser

func LaunchBrowser(page []byte) error

LaunchBrowser launches a web browser with the supplied HTML page. It can be used to display results pages returned by the CSS and HTML functions.

Types

type FileType

type FileType string

FileType describes the type of file being validated.

const (
	// Stylesheet is a standalone CSS stylesheet.
	Stylesheet FileType = "text/css"
	// HTMLDoc is an HTML document.
	HTMLDoc = "text/html"
)

type Issue

type Issue struct {
	// Severity describes the seriousness of the issue.
	Severity Severity
	// Line contains the 1-indexed line number where the issue occurred.
	// It is 0 if the line is unknown.
	Line int
	// Col contains the 1-indexed column number where the issue occurred.
	// It is 0 if the column is unknown.
	Col int
	// Message describes the issue.
	Message string
	// Code contains an optional code provided by the validator.
	Code string
	// Context optionally provides more detail about the context in which the issue occurred.
	Context string
	// Context optionally provides a URL with more information about the issue.
	URL string
}

Issue describes a problem reported by a validator.

func AMP

func AMP(ctx context.Context, r io.Reader) ([]Issue, error)

AMP reads an AMP HTML document from r and validates it by running the amphtml-validator program, which must be present in $PATH. Issues identified by the validator are parsed and returned. If the returned error is non-nil, an issue occurred in the validation process.

There unfortunately don't appear to be any online AMP validators that can be called programmatically. As a result, this function requires that the amphtml-validator Node.js program is installed locally. See https://amp.dev/documentation/guides-and-tutorials/learn/validation-workflow/validate_amp/#command-line-tool for more information about installing and running amphtml-validator.

More info about the lack of online validators:

The official AMP validator at https://validator.ampproject.org/ performs validation in the browser rather providing an HTTP server accepting posted documents.

Google provides an online AMP (and structured data) validator at https://search.google.com/test/amp, but it's very slow and it's not clear to me whether there's an easy way to use it outside of a web browser.

Cloudflare announced an online validator in 2017 at https://blog.cloudflare.com/amp-validator-api/, but it has since been shut down. That post points at https://blog.cloudflare.com/announcing-amp-real-url/ as justification, although I don't see any explanation of the validator's disappearance there.

The ampbench project seems to have provided an online validator, but it was apparently shut down in 2019 due to the codebase getting out of date: https://github.com/ampproject/ampbench/issues/126

There's more discussion at https://github.com/ampproject/amphtml/issues/1968.

func CSS

func CSS(ctx context.Context, r io.Reader, ft FileType) ([]Issue, []byte, error)

CSS reads an HTML or CSS document from r and validates its CSS content using https://jigsaw.w3.org/css-validator/. FileType describes the type of file being validated: the W3C validator seems to have the unfortunate property of reporting that the data validated successfully if the wrong type is supplied.

Parsed issues and the raw HTML results page returned by the validation service are returned. If the returned error is non-nil, an issue occurred in the validation process.

func HTML

func HTML(ctx context.Context, r io.Reader) ([]Issue, []byte, error)

HTML reads an HTML document from r and validates it using https://validator.w3.org/nu/. Parsed issues and the raw HTML results page returned by the validation service are returned. If the returned error is non-nil, an issue occurred in the validation process.

func (Issue) String

func (is Issue) String() string

type Severity

type Severity int

Severity describes the severity of an issue.

const (
	// Error indicates an actual problem, e.g. an unclosed HTML tag or invalid CSS property.
	Error Severity = iota
	// Warning indicates a minor issue, e.g. a vendor-prefixed CSS property.
	Warning
)

func (Severity) String

func (s Severity) String() string