Add handling of body & html; copy edits

enhance-dev · Jun 6, 2023 · 96d747c · 96d747c
1 parent dddfea0
commit 96d747c
Showing 1 changed file with 31 additions and 5 deletions.
diff --git a/app/docs/md/learn/starter-project/head.md b/app/docs/md/learn/starter-project/head.md
@@ -2,11 +2,9 @@
 title: Head
 ---
 
-The `<head>` tag is a very important point of customization for your app. You are going to want to add things like a custom title, favicons, social open graph meta, etc.
+The `<head>` tag is a very important point of customization for your app, allowing you to add things like a page titles, favicons, social/Open Graph metadata, etc.
 
-However, the `<head>` tag *is not a Custom Element*. Furthermore it cannot contain Custom Elements. There are only a subset of existing pre-defined HTML tags that can be included in the `<head>` tag.
-
-As Custom Elements are elements that you the user define they are not included in this pre-defined set of HTML tags.
+However, the `<head>` tag *is not a Custom Element*. Furthermore, it cannot contain Custom Elements. This is because — as defined by the HTML spec — only a subset of existing HTML tags are permitted in the `<head>` tag. As Custom Elements are elements which are defined by HTML authors, they are not included in this subset of permitted tags.
 
 <doc-callout level="none" mark="💀">
 
@@ -48,14 +46,16 @@ export default function Head () {
 
 Since the `<head>` tag *is not a Custom Element, nor can it be,* the arguments passed to `head.mjs` are not the same as Elements in your Enhance project.
 
-Since the `html` function passed to Elements is used to expand Custom Elements, which are not allowed inside the `<head>` tag, there is no reason to pass it as an argument. Instead your `head.mjs` template will be passed a `state` object containing:
+Since the `html` function passed to Elements is used to expand Custom Elements, which are not allowed inside the `<head>` tag, the Head component does not take the `html` function as an argument. Instead, your `head.mjs` template will be passed a `state` object containing:
 - store: [The API data mapped to the current page](/docs/learn/concepts/routing/api-routes)
 - req: [A standard request Object](/docs/learn/concepts/routing/api-routes#request)
 - error: An error message if an error has occurred so you can message your site's users
 - status: A status code to enable you to do the correct handling
 
 The example below demonstrates using some of these properties:
 
+<doc-code filename='app/head.mjs'>
+
 ```javascript
 import { getLinkTag } from '@enhance/arc-plugin-styles/get-styles'
 
@@ -77,12 +77,38 @@ export default function Head(state) {
 }
 ```
 
+</doc-code>
+
 <doc-callout level="none" mark="🚏">
 
 **[Read more about the `req` request object →](/docs/learn/concepts/routing/api-routes#request)**
 
 </doc-callout>
 
+## Automatic handling of `body` and `html` tags
+
+The Head component automatically handles creating an opening `body` tag if one is not declared in the template string it returns. However, if you would like to declare your own opening `body` tag (for example, to include a CSS class on every page of your app), the Head component will accommodate this too! For example:
+
+<doc-code filename='app/head.mjs'>
+
+```javascript
+export default function Head(state) {
+  /* … */
+  return `
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+      <!-- … -->
+    </head>
+    <body class="font-sans leading3">
+  `
+}
+```
+
+</doc-code>
+
+Additionally, Enhance will automatically render a closing `html` tag on every page, so there’s no need to include this in any of your own code.
+
 ## Templates that are not Custom Elements
 
 You are not limited to using Custom Elements when rendering your document server-side. You can define a template for pre-defined HTML tags as follows: