Add section about 'html metadata'. #2206

speced · Jan 8, 2022 · 8eaccd9 · 8eaccd9
1 parent c29faa6
commit 8eaccd9
Showing 1 changed file with 29 additions and 1 deletion.
diff --git a/docs/index.bs b/docs/index.bs
@@ -1410,6 +1410,34 @@ The ordering is, from first to last:
 
 In general, this follows the ordering of least-specific to most-specific.
 
+HTML "Metadata" (<code>lang=""</code>, <code>&lt;meta></code>, etc) {#metadata-html}
+-----------------------
+
+Generally, any HTML metadata
+(attributes on `<html>`,
+`<meta>` or `<link>` elements)
+should be handled in your `header.include` [[#boilerplate|boilerplate file]].
+However, sometimes you do need to add additional metadata
+to a specific document.
+
+For attributes that belong on `<html>`,
+such as `dir=""` or `lang=""`,
+simply add an `<html>` element with those attributes
+into your source file.
+A quirk of the HTML parser is that multiple `<html>` elements,
+wherever they appear,
+coalesce their attributes onto the one "true" `<html>` element
+that wraps the entire document,
+rather than actually showing up in the DOM.
+Bikeshed's serializer will then output the one true `<html>` element
+with all the coalesced attributes.
+
+Similarly, if you need to add `<meta>`, `<link>`, or `<style>` elements to your document,
+simply put them in your source.
+Bikeshed will automatically transfer them to the `<head>` of the output document.
+(`<script>` elements are left where they are,
+as their location can matter.)
+
 
 <!--
 ██     ██    ███    ████████  ██    ██ ██     ██ ████████
@@ -4050,7 +4078,7 @@ Here is a basic example `header.include` file:
 
 This uses several of Bikeshed's boilerplating features:
 
-* Text replacement, via the `\[FOO]` macros.
+* Text replacement, via the `[FOO]` macros.
 	These macros are prepopulated by Bikeshed,
 	either from metadata in the spec (like `[TITLE]`) or from environment data (like `[DATE]`).
 	The full list of text macros can be found at [[#text-macros]].