4.2. Document metadata
4.2.1. The head
element
- Categories:
- None.
- Contexts in which this element can be used:
- As the first element in an
html
element. - Content model:
- If the document is an
iframe
srcdoc
document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is atitle
element and no more than one is abase
element. - Otherwise: One or more elements of metadata content, of which exactly one is a
title
element and no more than one is abase
element. - Tag omission in text/html:
- A
head
element’s start tag may be omitted if the element is empty, or if the first thing inside thehead
element is an element. - A
head
element’s end tag may be omitted if thehead
element is not immediately followed by a space character or a comment. - Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- None
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- DOM interface:
-
interface HTMLHeadElement : HTMLElement {};
The head
element represents a collection of metadata for the Document
.
head
element can be large or small. Here is an
example of a very short one:
<!doctype html> <html lang="en"> <head> <title>A document with a short head</title> </head> <body> ...
Here is an example of a longer one:
<!DOCTYPE HTML> <HTML lang="en"> <HEAD> <META CHARSET="UTF-8"> <BASE HREF="https://www.example.com/"> <TITLE>An application with a long head</TITLE> <LINK REL="STYLESHEET" HREF="default.css"> <LINK REL="STYLESHEET ALTERNATE" HREF="big.css" TITLE="Big Text"> <SCRIPT SRC="support.js"></SCRIPT> <META NAME="APPLICATION-NAME" CONTENT="Long headed application"> </HEAD> <BODY> ...
The title
element is a required child in most situations, but when a higher-level
protocol provides title information, e.g., in the Subject line of an e-mail when HTML is used as
an e-mail authoring format, the title
element can be omitted.
It is recommended to keep the usage of attributes and their values defined on the head
element to a minimum to allow for proper detection of the character encoding declaration within the first 1024 bytes.
4.2.2. The title
element
- Categories:
- Metadata content.
- Contexts in which this element can be used:
- In a
head
element containing no othertitle
elements. - Content model:
- Text that is not inter-element white space.
- Tag omission in text/html:
- Neither tag is omissible.
- Content attributes:
- Global attributes
- Allowed ARIA role attribute values:
- None
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- DOM interface:
-
interface HTMLTitleElement : HTMLElement { attribute DOMString text; };
The title
element represents the document’s title or name. Authors should use
titles that identify their documents even when they are used out of context, for example in a
user’s history or bookmarks, or in search results. The document’s title is often different from
its first heading, since the first heading does not have to stand alone when taken out of context.
There must be no more than one title
element per document.
If it’s reasonable for the Document
to have no title, then the title
element is probably not required. See the head
element’s content model for a
description of when the element is required.
- title .
text
[ = value ] -
Returns the child text content of the element.
Can be set, to replace the element’s children with the given value.
text
must return the child text content of the title
element. On
setting, it must act the same way as the textContent
IDL attribute. <title>Introduction to The Mating Rituals of Bees</title> ... <h1>Introduction</h1> <p>This companion guide to the highly successful <cite>Introduction to Medieval Bee-Keeping</cite> book is...
The next page might be a part of the same site. Note how the title describes the subject matter unambiguously, while the first heading assumes the reader knows what the context is and therefore won’t wonder if the dances are Salsa or Waltz:
<title>Dances used during bee mating rituals</title> ... <h2>The Dances</h2>
The string to use as the document’s title is given by the document.title
IDL
attribute.
title
element are used in this way, the directionality of that title
element should be used to set the
directionality of the document’s title in the user interface. 4.2.3. The base
element
- Categories:
- Metadata content.
- Contexts in which this element can be used:
- In a
head
element containing no otherbase
elements. - Content model:
- Nothing.
- Tag omission in text/html:
- No end tag.
- Content attributes:
- Global attributes
href
— Document base URL-
target
— Default browsing context for hyperlink navigation and §4.10.21 Form submission - Allowed ARIA role attribute values:
- None
- Allowed ARIA state and property attributes:
- Global aria-* attributes.
- DOM interface:
-
interface HTMLBaseElement : HTMLElement { attribute DOMString href; attribute DOMString target; };
The base
element allows authors to specify the document base URL for the
purposes of §2.5.2 Parsing URLs, and the name of the default browsing context for the purposes of following hyperlinks. The element does not represent any content
beyond this information.
There must be no more than one base
element per document.
A base
element must have either an href
attribute, a target
attribute, or both.
The href
content attribute, if specified, must
contain a valid URL potentially surrounded by spaces.
A base
element, if it has an href
attribute, must come before any other elements in
the tree that have attributes defined as taking URLs, except the html
element
(its manifest
attribute isn’t affected by base
elements).
The target
attribute, if specified, must contain a valid browsing
context name or keyword, which specifies which browsing context is to be used as the
default when hyperlinks and forms in the Document
cause navigation.
A base
element, if it has a target
attribute, must come before any
elements in the tree that represent hyperlinks.
If there are multiple base
elements with target
attributes, all but
the first are ignored.
A base
element that is the first base
element with an href
content attribute in a document tree has a frozen base URL. The frozen base URL must be immediately set for an element whenever any of the following situations
occur:
-
The
base
element becomes the firstbase
element in tree order with anhref
content attribute in itsDocument
. -
The
base
element is the firstbase
element in tree order with anhref
content attribute in itsDocument
, and itshref
content attribute is changed.
To set the frozen base URL, for an element element:
-
Let document be element’s node document.
-
Let urlRecord be the result of parsing the value of element’s
href
content attribute with document’s fallback base URL, and document’s character encoding. (Thus thebase
element isn’t affected by itself.) -
Set elements’s frozen base URL to document’s fallback base URL, if urlRecord is failure or running Is base allowed for Document? on the resulting URL record and document returns "
Blocked
", and to urlRecord otherwise.
The href
IDL attribute, on getting, must
return the result of running the following algorithm:
-
Let document be element’s node document.
-
Let url be the value of the
href
attribute of thebase
element, if it has one, and the empty string otherwise. -
Let urlRecord be the result of parsing url with document’s fallback base url, and document’s character encoding. (Thus, the
base
element isn’t affected by otherbase
elements or itself). -
If urlRecord is failure, return url.
-
Return the serialization of urlRecord.
The href
IDL attribute, on setting, must set the href
content
attribute to the given new value.
The target
IDL attribute must reflect the content attribute of the same name.
base
element is used to set the document base URL:
<!DOCTYPE html> <html lang="en"> <head> <title>This is an example for the <base> element</title> <base href="https://www.example.com/news/index.html"> </head> <body> <p>Visit the <a href="archives.html">archives</a>.</p> </body> </html>
The link in the above example would be a link to
"https://www.example.com/news/archives.html
".
4.2.4. The link
element
- Categories:
- Metadata content.
- If the element is allowed in the body: flow content.
- If the element is allowed in the body: phrasing content.
- Contexts in which this element can be used:
- Where metadata content is expected.
- In a
noscript
element that is a child of ahead
element. - If the element is allowed in the body: where phrasing content is expected.
- Content model:
- Nothing.
- Tag omission in text/html:
- No end tag.
- Content attributes:
- Global attributes
href
— Address of the hyperlinkcrossorigin
— How the element handles crossorigin requestsrel
— Relationship of this document (or subsection/topic) to the destination resourcerev
— Reverse link relationship of the destination resource to this document (or subsection/topic)media
— Applicable medianonce
— Cryptographic nonce used in Content Security Policy checks [CSP3]hreflang
— Language of the linked resourcetype
— Hint for the type of the referenced resourcesizes
— Sizes of the icons (forrel
="icon
")- Also, the
title
attribute has special semantics on this element: Title of the link; alternative style sheet set name. - Allowed ARIA role attribute values:
link
(default - do not set).- Allowed ARIA state and property attributes:
- Global aria-* attributes
- Any
aria-*
attributes applicable to the default or allowed roles. - For
role
value - DOM interface:
-
interface HTMLLinkElement : HTMLElement { attribute DOMString href; attribute DOMString? crossOrigin; attribute DOMString rel; attribute DOMString rev; [SameObject, PutForwards=value]readonly attribute DOMTokenList relList; attribute DOMString media; attribute DOMString hreflang; attribute DOMString type; [SameObject, PutForwards=value] readonly attribute DOMTokenList sizes; }; HTMLLinkElement implements LinkStyle;
The link
element allows authors to link their document to other resources.
The destination of the link(s) is given by the href
attribute, which must
be present and must contain a valid non-empty URL potentially surrounded by spaces. If the href
attribute is absent, then the element does not define
a link.
A link
element must have a rel
attribute.
The types of link indicated (the relationships) are given by the value of the rel
attribute, which, if present, must have a
value that is a set of space-separated tokens. The allowed keywords and their
meanings are defined in a later section. If the rel
attribute is absent, has no
keywords, or if none of the keywords used are allowed according to the definitions in this
specification, then the element does not create any links.
If a link
element has a rel
attribute that contains only keywords that are body-ok, then the element is said to be allowed in the body. This means
that the element can be used where phrasing content is expected.
Two categories of links can be created using the link
element: Links to external resources and hyperlinks. The §4.8.6 Link types section defines
whether a particular link type is an external resource or a hyperlink. One link
element can create multiple links (of which some might be external resource links and some might
be hyperlinks); exactly which and how many links are created depends on the keywords given in the rel
attribute. User agents must process the links on a per-link
basis, not a per-element basis.
Each link created for a link
element is handled separately. For instance, if there
are two link
elements with rel="stylesheet"
, they each count as a
separate external resource, and each is affected by its own attributes independently. Similarly,
if a single link
element has a rel
attribute with the value next stylesheet
, it creates both a hyperlink (for the next
keyword) and an external resource link (for the stylesheet
keyword), and
they are affected by other attributes (such as media
or title
)
differently.
link
element creates two hyperlinks (to the same page):
<link rel="author license" href="/about">
The two links created by this element are one whose semantic is that the target page has information about the current page’s author, and one whose semantic is that the target page has information regarding the license under which the current page is provided.
link
and a
elements may also have a rev
attribute, which is used to describe
a reverse link relationship from the resource specified by the href
to the
current document. If present, the value of this attribute must be a set of space-separated
tokens. Like the rel
attribute, §4.8.6 Link types describes the allowed
keywords and their meanings for the rev
attribute. Both the rel
and rev
attributes may be present on the same element.
Reverse links are a way to express the reverse
directional relationship of a link. In contrast to the rel
attribute, whose value
conveys a forward directional relationship ("how is the link related to me"), the rev
attribute allows for similiar relationships to be expressed in the reverse direction ("how am I
related to this link"). These values can enable user agents to build a more comprehensive map of
linked documents.
rel
and rev
attributes as follows:
Document with URL "chapter1.html"
<link href="chapter2.html" rel="next" rev="prev">
Document with URL "chapter2.html"
<link href="chapter1.html" rel="prev" rev="next"> <link href="chapter3.html" rel="next" rev="prev">
From chapter1.html, the link to chapter2.html is the "next
" chapter in the series in
the forward direction, and the "previous
" chapter in the reverse diretion (from
chapter2.html to chapter1.html).
rel
and rev
as follows:
<ol> <li><a href="chapter1.html" rev="toc" rel="next">chapter 1</a></li> <li><a href="chapter2.html" rev="toc"></a>chapter 2</li> <li><a href="chapter3.html" rev="toc"></a>chapter 3</li> </ol>
From the table of contents, the "next
" logical path is to the first chapter,
expressed using rel
. Each chapter link has a "toc
" rev
value
which indicates that the current document is the table of contents document for every chapter.
The nonce
attribute represents a
cryptographic nonce ("number used once") which can be used by Content Security Policy to determine whether or not an external resource specified by the link will be loaded and applied
to the document. The value is text. [CSP3]
The crossorigin
attribute is a CORS settings attribute. It is intended for use with external resource links.
The exact behavior for links to external resources depends on the exact relationship, as defined for the relevant link type. Some of the attributes control whether or not the external resource is to be applied (as defined below).
For external resources that are represented in the DOM (for example, style sheets), the DOM representation must be made available (modulo cross-origin restrictions) even if the resource is not applied. To obtain the resource, the user agent must run the following steps:
-
If the
href
attribute’s value is the empty string, then abort these steps. -
Parse the URL given by the
href
attribute, relative to the element’s node document. If that fails, then abort these steps. Otherwise, let url be the resulting URL record. -
Let corsAttributeState be the current state of the element’s
crossorigin
content attribute. -
Let request be the result of creating a potential-CORS request given url and corsAttributeState.
-
Set request’s client to the
link
element’s node document’sWindow
object’s environment settings object. -
Set request’s cryptographic nonce metadata to the current state of the
link
element’snonce
content attribute. -
Fetch request.
User agents may opt to only try to obtain such resources when they are needed, instead of pro-actively fetching all the external resources that are not applied.
The semantics of the protocol used (e.g., HTTP) must be followed when fetching external resources. (For example, redirects will be followed and 404 responses will cause the external resource to not be applied.)
Once the attempts to obtain the resource and its critical subresources are complete, the
user agent must, if the loads were successful, queue a task to fire a simple event named load
at the link
element, or, if the resource or one of its critical subresources failed to completely load for any reason (e.g., DNS error, HTTP 404
response, a connection being prematurely closed, unsupported Content-Type), queue a task to fire a simple event named error
at the link
element.
Non-network errors in processing the resource or its subresources (e.g., CSS parse errors, PNG
decoding errors) are not failures for the purposes of this paragraph.
The task source for these tasks is the DOM manipulation task source.
The element must delay the load event of the element’s node document until all the attempts to obtain the resource and its critical subresources are complete. (Resources that the user agent has not yet attempted to obtain, e.g., because it is waiting for the resource to be needed, do not delay the load event.)
Interactive user agents may provide users with a means to follow the hyperlinks created
using the link
element, somewhere within their user interface. The exact interface
is not defined by this specification, but it could include the following information (obtained
from the element’s attributes, again as defined below), in some form or another (possibly
simplified), for each hyperlink created with each link
element in the document:
-
The relationship between this document and the resource (given by the
rel
attribute) -
The title of the resource (given by the
title
attribute). -
The address of the resource (given by the
href
attribute). -
The language of the resource (given by the
hreflang
attribute). -
The optimum media for the resource (given by the
media
attribute).
User agents could also include other information, such as the type of the resource (as given by
the type
attribute).
Hyperlinks created with the link
element and its rel
attribute apply
to the whole page. This contrasts with the rel
attribute of a
and area
elements, which indicates the type of a link whose context is given by the
link’s location within the document.
The media
attribute says which media the resource
applies to. The value must be a valid media query list.
media
attribute is purely advisory, and
describes for which media the document in question was designed.
However, if the link is an external resource link, then the media
attribute
is prescriptive. The user agent must apply the external resource when the media
attribute’s value matches the environment and the other relevant conditions apply, and
must not apply it otherwise.
The external resource might have further restrictions defined within that limit its
applicability. For example, a CSS style sheet might have some @media
blocks. This
specification does not override such further restrictions or requirements.
The default, if the media
attribute is omitted, is "all
", meaning that
by default links apply to all media.
The hreflang
attribute on the link
element has
the same semantics as the hreflang
attribute on the a
element.
The type
attribute gives the MIME type of
the linked resource. It is purely advisory. The value must be a valid mime type.
For external resource links, the type
attribute is used as a hint to user agents
so that they can avoid fetching resources they do not support. If the attribute is present, then
the user agent must assume that the resource is of the given type (even if that is not a valid mime type, e.g., the empty string). If the attribute is omitted, but the external
resource link type has a default type defined, then the user agent must assume that the resource
is of that type. If the user agent does not support the given MIME type for the given link
relationship, then the user agent should not obtain the resource; if the user agent does
support the given MIME type for the given link relationship, then the user agent should obtain the resource at the appropriate time as specified for the external resource link’s particular type. If the attribute is omitted, and the external
resource link type does not have a default type defined, but the user agent would obtain the resource if the type was known and supported, then the user agent should obtain the
resource under the assumption that it will be supported.
type
attribute authoritative — upon
fetching the resource, user agents must not use the type
attribute to determine its
actual type. Only the actual type (as defined in the next paragraph) is used to determine
whether to apply the resource, not the aforementioned assumed type.
If the external resource link type defines rules for processing the resource’s Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource’s Content-Type metadata, and use the resulting computed type of the resource as if it was the actual type. Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image sniffing rules, then the user agent must use the resource’s Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.
The stylesheet
link type defines rules for processing the resource’s Content-Type metadata.
Once the user agent has established the type of the resource, the user agent must apply the resource if it is of a supported type and the other relevant conditions apply, and must ignore the resource otherwise.
<link rel="stylesheet" href="A" type="text/plain"> <link rel="stylesheet" href="B" type="text/css"> <link rel="stylesheet" href="C">
...then a compliant user agent that supported only CSS style sheets would fetch the B and C
files, and skip the A file (since text/plain
is not the MIME type for CSS
style sheets).
For files B and C, it would then check the actual types returned by the server. For those that
are sent as text/css
, it would apply the styles, but for those labeled as text/plain
, or any other type, it would not.
If one of the two files was returned without a Content-Type metadata, or with a
syntactically incorrect type like Content-Type: "null"
, then the default type
for stylesheet
links would kick in. Since that default type is text/css
, the style sheet would nonetheless be applied.
The title
attribute gives the title of the link.
With one exception, it is purely advisory. The value is text. The exception is for style sheet
links, where the title
attribute defines alternative style sheet sets.
The title
attribute on link
elements differs from the global title
attribute of most other elements in that a link without a title does not inherit the title of
the parent element: it merely has no title.
The sizes
attribute is used with the icon
link type. The attribute must
not be specified on link
elements that do not have a rel
attribute that
specifies the icon
keyword or the apple-touch-icon
keyword.
Note: The apple-touch-icon
keyword is a registered extension to the predefined set of link types, but user agents
are not required to support it in any way.
link
elements that create hyperlinks is to
run the following steps:
-
If the
link
element’s node document is not fully active, then abort these steps. -
Follow the hyperlink created by the
link
element.
HTTP Link:
headers, if supported, must be assumed to come before any links in the
document, in the order that they were given in the HTTP message. These headers are to be
processed according to the rules given in the relevant specifications. [HTTP] [RFC5988]
Registration of relation types in HTTP Link: headers is distinct from HTML link types, and thus their semantics can be different from same-named HTML types.
The IDL attributes href
, rel
, rev
, media
, nonce
, hreflang
, type
, and sizes
each must reflect the
respective content attributes of the same name.
The crossOrigin
IDL attribute must reflect the crossorigin
content attribute.
The IDL attribute relList
must reflect the rel
content attribute.
relList
’s DOMTokenList
's supported tokens are the keywords
defined in HTML link types which are allowed on link
elements and supported
by the user agent.
rel
's supported tokens are the keywords defined in HTML link types which
are allowed on link
elements, impact the processing model, and are supported by the user
agent. The possible supported tokens are alternate
, dns-prefetch
, icon
, preconnect
, prefetch
, prerender
, search
, stylesheet
and next
. rel
's supported tokens must only
include the tokens from this list that the user agent implements the processing model for.
Other specifications may add HTML link types as defined in Other link types, with the following additional requirements:
The LinkStyle
interface is also implemented by this element. [CSSOM]
link
elements provide some style sheets:
<!-- a persistent style sheet --> <link rel="stylesheet" href="default.css"> <!-- the preferred alternate style sheet --> <link rel="stylesheet" href="green.css" title="Green styles"> <!-- some alternate style sheets --> <link rel="alternate stylesheet" href="contrast.css" title="High contrast"> <link rel="alternate stylesheet" href="big.css" title="Big fonts"> <link rel="alternate stylesheet" href="wide.css" title="Wide screen">
<link rel=alternate href="/en/html" hreflang=en type=text/html title="English HTML"> <link rel=alternate href="/fr/html" hreflang=fr type=text/html title="French HTML"> <link rel=alternate href="/en/html/print" hreflang=en type=text/html media=print title="English HTML (for printing)"> <link rel=alternate href="/fr/html/print" hreflang=fr type=text/html media=print title="French HTML (for printing)"> <link rel=alternate href="/en/pdf" hreflang=en type=application/pdf title="English PDF"> <link rel=alternate href="/fr/pdf" hreflang=fr type=application/pdf title="French PDF">
4.2.5. The meta
element
- Categories:
- Metadata content.
- Contexts in which this element can be used:
- If the
charset
attribute is present, or if the element’shttp-equiv
attribute is in the encoding declaration state: in ahead
element. - If the
http-equiv
attribute is present but not in the encoding declaration state: in ahead
element. - If the
http-equiv
attribute is present but not in the encoding declaration state: in anoscript
element that is a child of ahead
element. - If the
name
attribute is present: where metadata content is expected. - Content model:
- Nothing.
- Tag omission in text/html:
- No end tag.
- Content attributes:
- Global attributes
name
— Metadata namehttp-equiv
— Pragma directivecontent
— Value of the elementcharset
— Character encoding declaration- Allowed ARIA role attribute values:
- None
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- DOM interface:
-
interface HTMLMetaElement : HTMLElement { attribute DOMString name; attribute DOMString httpEquiv; attribute DOMString content; };
The meta
element represents various kinds of metadata that cannot be
expressed using the title
, base
, link
, style
,
and script
elements.
The meta
element can represent document-level metadata with the name
attribute, pragma directives with the http-equiv
attribute, and the file’s character encoding declaration when an HTML document is serialized to string form (e.g., for
transmission over the network or for disk storage) with the charset
attribute.
Exactly one of the name
, http-equiv
, and charset
attributes must be specified.
If either name
or http-equiv
is
specified, then the content
attribute must also be
specified. Otherwise, it must be omitted.
The charset
attribute specifies the character
encoding used by the document. This is a character encoding declaration. If the
attribute is present in an XML document, its value must be an ASCII case-insensitive match for the string "utf-8
" (and the
document is therefore forced to use UTF-8 as its encoding).
The charset
attribute on the meta
element has no effect in XML documents, and is only allowed in order to
facilitate migration to and from XHTML.
There must not be more than one meta
element with a charset
attribute
per document.
The content
attribute gives the value of the
document metadata or pragma directive when the element is used for those purposes. The allowed
values depend on the exact context, as described in subsequent sections of this specification.
<meta name="viewport" content="...">
allows authors to define specific viewport characteristics (such as the layout viewport’s width and zoom factor)
for their documents. Among these is the ability to prevent or restrict users from being able to zoom, using content
values such as user-scalable=no
or maximum-scale=1.0
. Authors should not suppress
or limit the ability of users to resize a document, as this causes accessibility and usability issues.
<!-- DO NOT DO THIS --> <meta name="viewport" content="user-scalable=no"> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">
There may be specific use cases where preventing users from zooming may be appropriate, such as map applications – where custom zoom functionality is handled via scripting. However, in general this practice should be avoided, and HTML conformance checking tools should display a warning if they encounter these values.
Note that most user agents now allow users to always zoom, regardless of any <meta name="viewport" content="...">
restrictions – either by default, or as a setting/option (which may however not be immediately apparent to users).
If a meta
element has a name
attribute, it sets document metadata. Document metadata is expressed in terms of name-value pairs,
the name
attribute on the meta
element giving the
name, and the content
attribute on the same element giving
the value. The name specifies what aspect of metadata is being set; valid names and the meaning of
their values are described in the following sections. If a meta
element has no content
attribute, then the value part of the metadata name-value pair is the empty
string.
The name
and content
IDL attributes must reflect the respective content attributes of the same name. The IDL attribute httpEquiv
must reflect the content attribute http-equiv
.
4.2.5.1. Standard metadata names
This specification defines a few names for the name
attribute of the meta
element.
Names are case-insensitive, and must be compared in an ASCII case-insensitive manner.
application-name
-
The value must be a short free-form string giving the name of the Web application that the page represents. If the page is not a Web application, the
application-name
metadata name must not be used. Translations of the Web application’s name may be given, using thelang
attribute to specify the language of each name.There must not be more than one
meta
element with a given language and with itsname
attribute set to the valueapplication-name
per document.User agents may use the application name in UI in preference to the page’stitle
, since the title might include status messages and the like relevant to the status of the page at a particular moment in time instead of just being the name of the application.To find the application name to use given an ordered list of languages (e.g., British English, American English, and English), user agents must run the following steps:
-
Let languages be the list of languages.
-
Let default language be the language of the
Document
's document element, if any, and if that language is not unknown. -
If there is a default language, and if it is not the same language as any of the languages in languages, append it to languages.
-
Let winning language be the first language in languages for which there is a
meta
element in theDocument
that has itsname
attribute set to the valueapplication-name
and whose language is the language in question.If none of the languages have such a
meta
element, then abort these steps; there’s no given application name. -
Return the value of the
content
attribute of the firstmeta
element in theDocument
in tree order that has itsname
attribute set to the valueapplication-name
and whose language is winning language.
This algorithm would be used by a browser when it needs a name for the page, for instance, to label a bookmark. The languages it would provide to the algorithm would be the user’s preferred languages.
-
author
-
The value must be a free-form string giving the name of one of the page’s authors.
description
-
The value must be a free-form string that describes the page. The value must be appropriate for use in a directory of pages, e.g., in a search engine. There must not be more than one
meta
element with itsname
attribute set to the valuedescription
per document. generator
-
The value must be a free-form string that identifies one of the software packages used to generate the document. This value must not be used on pages whose markup is not generated by software, e.g., pages whose markup was written by a user in a text editor.
Here is what a tool called "Frontweaver" could include in its output, in the page’shead
element, to identify itself as the tool used to generate the page:<meta name=generator content="Frontweaver 8.2">
keywords
-
The value must be a set of comma-separated tokens, each of which is a keyword relevant to the page.
This page about typefaces on British motorways uses ameta
element to specify some keywords that users might use to look for the page:<!DOCTYPE HTML> <html lang="en-GB"> <head> <title>Typefaces on UK motorways</title> <meta name="keywords" content="british,type face,font,fonts,highway,highways"> </head> <body> ...
Many search engines do not consider such keywords, because this feature has historically been used unreliably and even misleadingly as a way to spam search engine results in a way that is not helpful for users.
To obtain the list of keywords that the author has specified as applicable to the page, the user agent must run the following steps:-
Let keywords be an empty list.
-
For each
meta
element with aname
attribute and acontent
attribute and whosename
attribute’s value iskeywords
, run the following substeps:-
Split the value of the element’s
content
attribute on commas. -
Add the resulting tokens, if any, to keywords.
-
-
Remove any duplicates from keywords.
-
Return keywords. This is the list of keywords that the author has specified as applicable to the page.
User agents should not use this information when there is insufficient confidence in the reliability of the value.
For instance, it would be reasonable for a content management system to use the keyword information of pages within the system to populate the index of a site-specific search engine, but a large-scale content aggregator that used this information would likely find that certain users would try to game its ranking mechanism through the use of inappropriate keywords.
-
4.2.5.2. Other metadata names
Extensions to the predefined set of metadata names may be registered in the WHATWG Wiki MetaExtensions page. [WHATWGWIKI]
Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a type. These new names must be specified with the following information:
- Keyword
-
The actual name being defined. The name should not be confusingly similar to any other defined name (e.g., differing only in case).
- Brief description
-
A short non-normative description of what the metadata name’s meaning is, including the format the value is required to be in.
- Specification
-
A link to a more detailed description of the metadata name’s semantics and requirements. It could be another page on the Wiki, or a link to an external page.
- Synonyms
-
A list of other names that have exactly the same processing requirements. Authors should not use the names defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.
- Status
-
One of the following:
- Proposed
-
The name has not received wide peer review and approval. Someone has proposed it and is, or soon will be, using it.
- Ratified
-
The name has received wide peer review and approval. It has a specification that unambiguously defines how to handle pages that use the name, including when they use it in incorrect ways.
- Discontinued
-
The metadata name has received wide peer review and it has been found wanting. Existing pages are using this metadata name, but new pages should avoid it. The "brief description" and "specification" entries will give details of what authors should use instead, if anything.
If a metadata name is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.
If a metadata name is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.
If a metadata name is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a metadata name is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.
Anyone can change the status at any time, but should only do so in accordance with the definitions above.
When an author uses a new metadata name not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposed" status.
Metadata names whose values are to be URLs must not be proposed or accepted. Links must be
represented using the link
element, not the meta
element.
4.2.5.3. Pragma directives
When the http-equiv
attribute is specified on a meta
element,
the element is a pragma directive.
The http-equiv
attribute is an enumerated attribute. The following table lists
the keywords defined for this attribute. The states given in the first cell of the rows with
keywords give the states to which those keywords map. Some of the keywords are
non-conforming, as noted in the last column.
State | Keyword | Notes |
---|---|---|
Content Language | content-language
| Non-conforming |
Encoding declaration | content-type
| |
Default style | default-style
| |
Refresh | refresh
| |
Cookie setter | set-cookie
| Non-conforming |
meta
element is inserted into the document, if its http-equiv
attribute is present and represents one of the above states, then the
user agent must run the algorithm appropriate for that state, as described in the following
list: - Content language state (
http-equiv="content-language"
) -
This feature is non-conforming. Authors are encouraged to use the
lang
attribute instead.This pragma sets the pragma-set default language. Until such a pragma is successfully processed, there is no pragma-set default language.
-
If the
meta
element has nocontent
attribute, then abort these steps. -
If the element’s
content
attribute contains a U+002C COMMA character (,) then abort these steps. -
Let input be the value of the element’s
content
attribute. -
Let position point at the first character of input.
-
Collect a sequence of characters that are not space characters.
-
Let candidate be the string that resulted from the previous step.
-
If candidate is the empty string, abort these steps.
-
Set the pragma-set default language to candidate.
If the value consists of multiple space-separated tokens, tokens after the first are ignored.
This pragma is not the same as the HTTP
Content-Language
header of the same name. HTTPContent-Language
values with more than one language tag will be rejected as invalid by this pragma. [HTTP] -
- Encoding declaration state (
http-equiv="content-type"
) -
The encoding declaration state is just an alternative form of setting the
charset
attribute: it is a character encoding declaration. This state’s user agent requirements are all handled by the parsing section of the specification.For
meta
elements with anhttp-equiv
attribute in the encoding declaration state, thecontent
attribute must have a value that is an ASCII case-insensitive match for a string that consists of: the literal string "text/html;
", optionally followed by any number of space characters, followed by the literal string "charset=
", followed by one of the labels of the character encoding of the character encoding declaration.A document must not contain both a
meta
element with anhttp-equiv
attribute in the encoding declaration state and ameta
element with thecharset
attribute present.The encoding declaration state may be used in HTML documents and in XML Documents. If the encoding declaration state is used in XML Documents, the name of the character encoding must be an ASCII case-insensitive match for the string "
UTF-8
" (and the document is therefore forced to use UTF-8 as its encoding).The encoding declaration state has no effect in XML documents, and is only allowed in order to facilitate migration to and from XHTML.
- Default style state (
http-equiv="default-style"
) -
This pragma sets the name of the default alternative style sheet set.
-
If the
meta
element has nocontent
attribute, or if that attribute’s value is the empty string, then abort these steps. -
Set the preferred style sheet set to the value of the element’s
content
attribute. [CSSOM]
-
- Refresh state (
http-equiv="refresh"
) -
This pragma acts as timed redirect.
-
If another
meta
element with anhttp-equiv
attribute in the Refresh state has already been successfully processed (i.e., when it was inserted the user agent processed it and reached the step labeled end), then abort these steps. -
If the
meta
element has nocontent
attribute, or if that attribute’s value is the empty string, then abort these steps. -
Let input be the value of the element’s
content
attribute. -
Let position point at the first character of input.
-
Collect a sequence of characters that are ASCII digits, and parse the resulting string using the rules for parsing non-negative integers. If the sequence of characters collected is the empty string, then no number will have been parsed; abort these steps. Otherwise, let time be the parsed number.
-
Collect a sequence of characters that are ASCII digits and U+002E FULL STOP characters (.). Ignore any collected characters.
-
Let url be the
meta
element’s node document’s URL. -
If position is past the end of input, jump to the step labeled end.
-
If the character in input pointed to by position is not a U+003B SEMICOLON character (;), a U+002C COMMA character (,), or a space character, then abort these steps.
-
If the character in input pointed to by position is a U+003B SEMICOLON character (;), a U+002C COMMA character (,), then advance position to the next character.
-
If position is past the end of input, jump to the step labeled end.
-
Let url be equal to the substring of input from the character at position to the end of the string.
-
If the character in input pointed to by position is a U+0055 LATIN CAPITAL LETTER U character (U) or a U+0075 LATIN SMALL LETTER U character (u), then advance position to the next character. Otherwise, jump to the step labeled skip quotes.
-
If the character in input pointed to by position is a U+0052 LATIN CAPITAL LETTER R character (R) or a U+0072 LATIN SMALL LETTER R character (r), then advance position to the next character. Otherwise, jump to the step labeled Parse.
-
If the character in input pointed to by position is s U+004C LATIN CAPITAL LETTER L character (L) or a U+006C LATIN SMALL LETTER L character (l), then advance position to the next character. Otherwise, jump to the step labeled Parse.
-
If the character in input pointed to by position is a U+003D EQUALS SIGN (=), then advance position to the next character. Otherwise, jump to the step step labeled Parse.
-
Skip quotes: If the character in input pointed to by position is either a U+0027 APOSTROPHE character (') or U+0022 QUOTATION MARK character ("), then let quote be that character, and advance position to the next character. Otherwise, let quote be the empty string.
-
Let url be equal to the substring of input from the character at position to the end of the string.
-
If quote is not the empty string, and there is a character in url equal to quote, then truncate url at that character, so that it and all subsequent characters are removed.
-
Parse: Parse url relative to the
meta
element’s node document. If that fails, abort these steps. Otherwise, let urlRecord be the resulting URL record. -
End: Perform one or more of the following steps:
-
After the refresh has come due (as defined below), if the user has not canceled the redirect and if the
meta
element’s node document’s active sandboxing flag set does not have the sandboxed automatic features browsing context flag set, navigate theDocument
's browsing context to urlRecord, with replacement enabled, and with theDocument
's browsing context as the source browsing context.For the purposes of the previous paragraph, a refresh is said to have come due as soon as the later of the following two conditions occurs:
-
At least time seconds have elapsed since the document has completely loaded, adjusted to take into account user or user agent preferences.
-
At least time seconds have elapsed since the
meta
element was inserted into the document, adjusted to take into account user or user agent preferences.
-
-
Provide the user with an interface that, when selected, navigates a browsing context to urlRecord, with the
Document
's browsing context as the source browsing context. -
Do nothing.
In addition, the user agent may, as with anything, inform the user of any and all aspects of its operation, including the state of any timers, the destinations of any timed redirects, and so forth.
-
For
meta
elements with anhttp-equiv
attribute in the Refresh state, thecontent
attribute must have a value consisting either of:-
just a valid non-negative integer, or
-
a valid non-negative integer, followed by a U+003B SEMICOLON character (;), followed by one or more space characters, followed by a substring that is an ASCII case-insensitive match for the string "
URL
", followed by a U+003D EQUALS SIGN character (=), followed by a valid URL that does not start with a literal U+0027 APOSTROPHE (') or U+0022 QUOTATION MARK (") character.
In the former case, the integer represents a number of seconds before the page is to be reloaded; in the latter case the integer represents a number of seconds before the page is to be replaced by the page at the given URL.
A news organization’s front page could include the following markup in the page’shead
element, to ensure that the page automatically reloads from the server every five minutes:<meta http-equiv="Refresh" content="300">
A sequence of pages could be used as an automated slide show by making each page refresh to the next page in the sequence, using markup such as the following:<meta http-equiv="Refresh" content="20; URL=page4.html">
- Cookie setter (
http-equiv="set-cookie"
) -
This pragma sets an HTTP cookie. [COOKIES]
It is non-conforming. Real HTTP headers should be used instead.
-
If the
meta
element has nocontent
attribute, or if that attribute’s value is the empty string, then abort these steps. -
Act as if receiving a set-cookie-string for the document’s URL via a "non-HTTP" API, consisting of the value of the element’s
content
attribute encoded as UTF-8. [COOKIES] [ENCODING]
-
- Content security policy state (
http-equiv="content-security-policy"
) -
This pragma enforces a Content Security Policy on a
Document
. [CSP3]-
If the
meta
element is not a child of ahead
element, abort these steps. -
If the
meta
element has nocontent
attribute, or if that attribute’s value is the empty string, then abort these steps. -
Let policy be the result of executing Content Security Policy’s parse a serialized Content Security Policy algorithm on the
meta
element’scontent
attribute’s value. -
Remove all occurrences of the
report-uri
,frame-ancestors
, andsandbox
directives from policy. -
Enforce the policy policy.
For
meta
elements with anhttp-equiv
attribute in the Content security policy state, thecontent
attribute must have a value consisting of a valid Content Security Policy, but must not contain anyreport-uri
,frame-ancestors
, orsandbox
directives. The Content Security Policy given in thecontent
attribute will be enforced upon the current document. [CSP3] -
-
There must not be more than one meta
element with any particular state in the
document at a time.
4.2.5.4. Other pragma directives
Extensions to the predefined set of pragma directives may, under certain conditions, be registered in the WHATWG Wiki PragmaExtensions page. [WHATWGWIKI]
Such extensions must use a name that is identical to an HTTP header registered in the Permanent Message Header Field Registry, and must have behavior identical to that described for the HTTP header. [IANAPERMHEADERS]
Pragma directives corresponding to headers describing metadata, or not requiring specific user agent processing, must not be registered; instead, use metadata names. Pragma directives corresponding to headers that affect the HTTP processing model (e.g., caching) must not be registered, as they would result in HTTP-level behavior being different for user agents that implement HTML than for user agents that do not.
Anyone is free to edit the WHATWG Wiki PragmaExtensions page at any time to add a pragma directive satisfying these conditions. Such registrations must specify the following information:
- Keyword
-
The actual name being defined. The name must match a previously-registered HTTP name with the same requirements.
- Brief description
-
A short non-normative description of the purpose of the pragma directive.
- Specification
-
A link to the specification defining the corresponding HTTP header.
4.2.5.5. Specifying the document’s character encoding
A character encoding declaration is a mechanism by which the character encoding used to store or transmit a document is specified.
The following restrictions apply to character encoding declarations:
-
The character encoding name given must be an ASCII case-insensitive match for one of the labels of the character encoding used to serialize the file. [ENCODING]
-
The character encoding declaration must be serialized without the use of character references or character escapes of any kind.
-
The element containing the character encoding declaration must be serialized completely within the first 1024 bytes of the document.
In addition, due to a number of restrictions on meta
elements, there can only be one meta
-based character encoding declaration per document.
If an HTML document does not start with a BOM, and its encoding is not explicitly
given by Content-Type metadata, and the document is not an iframe
srcdoc
document, then the character encoding used must be an ASCII-compatible encoding, and the encoding must be specified using a meta
element with a charset
attribute or a meta
element with an http-equiv
attribute in the encoding declaration state.
A character encoding declaration is required (either in the Content-Type metadata or explicitly in the file) even if the encoding is US-ASCII, because a character encoding is needed to process non-ASCII characters entered by the user in forms, in URLs generated by scripts, and so forth.
If the document is an iframe
srcdoc
document, the document must
not have a character encoding declaration. (In this case, the source is already decoded,
since it is part of the document that contained the iframe
.)
If an HTML document contains a meta
element with a charset
attribute or a meta
element with an http-equiv
attribute in the encoding declaration state, then the character encoding used must be an ASCII-compatible encoding.
Authors should use UTF-8. Conformance checkers may advise authors against using legacy encodings. [ENCODING]
Authoring tools should default to using UTF-8 for newly-created documents. [ENCODING]
Authors must not use encodings that are not defined in the WHATWG Encoding specification. Additionally, authors should not use ISO-2022-JP. [ENCODING]
Some encodings that are not defined in the WHATWG Encoding specification use bytes in the range 0x20 to 0x7E, inclusive, to encode characters other than the corresponding characters in the range U+0020 to U+007E, inclusive, and represent a potential security vulnerability: A user agent might end up interpreting supposedly benign plain text content as HTML tags and JavaScript.
Using non-UTF-8 encodings can have unexpected results on form submission and URL encodings, which use the document’s character encoding by default.
In XHTML, the XML declaration should be used for inline character encoding information, if necessary.
head
element):
<meta charset="utf-8">
In XML, the XML declaration would be used instead, at the very top of the markup:
<?xml version="1.0" encoding="utf-8"?>
4.2.6. The style
element
- Categories:
- Metadata content.
- Contexts in which this element can be used:
- Where metadata content is expected.
- In a
noscript
element that is a child of ahead
element. - Content model:
- Depends on the value of the
type
attribute, but must match requirements described in prose below. - Tag omission in text/html:
- Neither tag is omissible.
- Content attributes:
- Global attributes
media
— Applicable medianonce
- Cryptographic nonce used in Content Security Policy checks [CSP3]type
— Type of embedded resource- Also, the
title
attribute has special semantics on this element: Alternative style sheet set name. - Allowed ARIA role attribute values:
- None
- Allowed ARIA state and property attributes:
- Global aria-* attributes
- DOM interface:
-
interface HTMLStyleElement : HTMLElement { attribute DOMString media; attribute DOMString nonce; attribute DOMString type; }; HTMLStyleElement implements LinkStyle;
The style
element allows authors to embed style information in their documents. The style
element is one of several inputs to the styling processing model. The element
does not represent content for the user.
The type
attribute gives the styling language. If the attribute is
present, its value must be a valid mime type that designates a styling language. The charset
parameter must not be specified. The default value for the type
attribute, which is used if the attribute is absent, is "text/css
". [RFC2318]
charset
parameter must be treated as an unknown parameter for the purpose of
comparing MIME types here. The media
attribute says which media the styles apply to. The value must
be a valid media query list. The user agent must apply the styles when
the media
attribute’s value matches the environment and the other relevant
conditions apply, and must not apply them otherwise.
The styles might be further limited in scope, e.g., in CSS with the use of @media
blocks. This specification does not override such further restrictions or requirements.
The default, if the media
attribute is omitted, is "all
", meaning that
by default styles apply to all media.
A style
element should preferably be used in the head
of the document.
The use of style
in the body
of the document may cause restyling, trigger layout
and/or cause repainting, and hence, should be used with care.
The nonce
attribute represents a cryptographic
nonce ("number used once") which can be used by Content Security Policy to determine
whether or not the style specified by an element will be applied to the document. The value is
text. [CSP3]
The title
attribute on style
elements defines alternative style sheet sets. If the style
element has no title
attribute, then it has no title; the title
attribute of ancestors does not apply to
the style
element. [CSSOM]
The title
attribute on style
elements, like the title
attribute on link
elements, differs from the global title
attribute in
that a style
block without a title does not inherit the title of the parent
element: it merely has no title.
The textContent
of a style
element must match the style
production in the following ABNF, the character set for which is Unicode. [ABNF]
style = no-c-start *( c-start no-c-end c-end no-c-start ) no-c-start = < any string that doesn’t contain a substring that matches c-start > c-start = "<!--" no-c-end = < any string that doesn’t contain a substring that matches c-end > c-end = "-->"
style
block algorithm that
applies for the style sheet language specified by the style
element’s type
attribute, passing it the element’s style data, whenever one of the following
conditions occur:
-
the element is popped off the stack of open elements of an HTML parser or XML parser,
-
the element is not on the stack of open elements of an HTML parser or XML parser, and it is inserted into a document or removed from a document,
-
the element is not on the stack of open elements of an HTML parser or XML parser, and one of its child nodes is modified by a script,
For styling languages that consist of pure text (as opposed to XML), a style
element’s style data is the child text content of the style
element (not any
other nodes such as comments or elements), in tree order. For XML-based styling
languages, the style data consists of all the child nodes of the style
element.
The update a style
block algorithm for CSS (text/css
) is as
follows:
-
Let element be the
style
element. -
If element has an associated CSS style sheet, remove the CSS style sheet in question.
-
If element is not in a
Document
, then abort these steps. -
If the Should element’s inline behavior be blocked by Content Security Policy? algorithm returns "
Blocked
" when executed upon thestyle
element, "style
", and thestyle
element’s style data, then abort these steps. [CSP3] -
create a CSS style sheet with the following properties:
- type
-
text/css
- owner node
-
element
- media
-
The
media
attribute of element.This is a reference to the (possibly absent at this time) attribute, rather than a copy of the attribute’s current value. The CSSOM specification defines what happens when the attribute is dynamically set, changed, or removed.
- title
-
The
title
attribute of element.Again, this is a reference to the attribute.
- alternate flag
-
Unset.
- origin-clean flag
-
Set.
- parent CSS style sheet
- owner CSS rule
-
null
- disabled flag
-
Left at its default value.
- CSS rules
-
Left uninitialized.
This specification does not define any other styling language’s update a style
block algorithm.
Once the attempts to obtain the style sheet’s critical subresources, if any, are
complete, or, if the style sheet has no critical subresources, once the style sheet has
been parsed and processed, the user agent must, if the loads were successful or there were none, queue a task to fire a simple event named load
at the style
element, or, if one of the style sheet’s critical subresources failed
to completely load for any reason (e.g., DNS error, HTTP 404 response, a connection being
prematurely closed, unsupported Content-Type), queue a task to fire a simple event named error
at the style
element. Non-network errors in processing the
style sheet or its subresources (e.g., CSS parse errors, PNG decoding errors) are not failures
for the purposes of this paragraph.
The task source for these tasks is the DOM manipulation task source.
The element must delay the load event of the element’s node document until all the attempts to obtain the style sheet’s critical subresources, if any, are complete.
This specification does not specify a style system, but CSS is expected to be supported by most Web browsers. [CSS-2015]
media
, nonce
, and type
IDL attributes must reflect the respective content
attributes of the same name. The LinkStyle
interface is also implemented by this element. [CSSOM]
<!DOCTYPE html><html> <head> <title>My favorite book</title> <style> body { color: black; background: white; } em { font-style: normal; color: red; } </style> </head> <body> <p>My <em>favorite</em> book of all time has <em>got</em> to be <cite>A Cat’s Life</cite>. It is a book by P. Rahmel that talks about the <i lang="la">Felis Catus</i> in modern human society.</p> </body> </html>
4.2.7. Interactions of styling and scripting
Style sheets, whether added by a link
element, a style
element, an <?xml-stylesheet?>
PI, an HTTP Link
header, or some other
mechanism, have a style sheet ready flag, which is initially unset.
When a style sheet is ready to be applied, its style sheet ready flag must be set. If the
style sheet referenced no other resources (e.g., it was an internal style sheet given by a style
element with no @import
rules), then the style rules must be immediately made available to script; otherwise, the style rules must only be made
available to script once the event loop reaches its update the rendering step.
A style sheet in the context of the Document
of an HTML parser or XML parser is
said to be a style sheet that is blocking scripts if the element was created by that Document
's parser, and the element is either a style
element or a link
element that
was an external resource link when the element was created by
the parser, and the element’s style sheet was enabled when the element was created by the parser,
and the element’s style sheet ready flag is not yet set, and, the last time the event loop reached step 1, the element was in that Document
, and the user
agent hasn’t given up on that particular style sheet yet. A user agent may give up on a style
sheet at any time.
Giving up on a style sheet before the style sheet loads, if the style sheet eventually does still load, means that the script might end up operating with incorrect information. For example, if a style sheet sets the color of an element to green, but a script that inspects the resulting style is executed before the sheet is loaded, the script will find that the element is black (or whatever the default color is), and might thus make poor choices (e.g., deciding to use black as the color elsewhere on the page, instead of green). Implementors have to balance the likelihood of a script using incorrect information with the performance impact of doing nothing while waiting for a slow network request to finish.
A Document
has a style sheet that is blocking scripts if there is either a style sheet that is blocking scripts in the context of that Document
, or
if that Document
is in a browsing context that has a parent browsing context, and the active document of that parent browsing context itself has a style sheet that is blocking scripts.
A Document
has no style sheet that is blocking scripts if it does not have a style sheet that is blocking scripts as defined in the previous paragraph.