docs: update `transformHead` (#5191)

2 months ago · cd4ed0537b
parent 4967e9bab4
commit cd4ed0537b
1 changed files with 59 additions and 29 deletions
--- a/docs/en/reference/site-config.md
+++ b/docs/en/reference/site-config.md
@ -607,7 +607,7 @@ interface SSGContext {

 - Type: `(context: TransformContext) => Awaitable<HeadConfig[]>`

-`transformHead` is a build hook to transform the head before generating each page. It will allow you to add head entries that cannot be statically added to your VitePress config. You only need to return extra entries, they will be merged automatically with the existing ones.
+`transformHead` is a build hook to add extra tags to the `<head>` of each page. It allows you to add head entries that cannot be statically added to your VitePress config. You only need to return extra entries, they will be merged automatically with the existing ones.

 ::: warning
 Don't mutate anything inside the `context`.
@ -635,44 +635,38 @@ interface TransformContext {
 }
 ```

-Note that this hook is only called when generating the site statically. It is not called during dev. If you need to add dynamic head entries during dev, you can use the [`transformPageData`](#transformpagedata) hook instead:
+This hook is only called when performing a build, it is not called during dev.

-```ts
-export default {
-  transformPageData(pageData) {
-    pageData.frontmatter.head ??= []
-    pageData.frontmatter.head.push([
-      'meta',
-      {
-        name: 'og:title',
-        content:
-          pageData.frontmatter.layout === 'home'
-            ? `VitePress`
-            : `${pageData.title} | VitePress`
-      }
-    ])
-  }
-}
-```
+The extra tags will be added to the static HTML files generated by the build. They will not be updated during client-side navigation.

-#### Example: Adding a canonical URL `<link>`
+In many cases, using the [`transformPageData`](#transformpagedata) hook is a cleaner solution. That hook will also be applied to both client-side navigation and during dev. But if generating the head tags is computationally expensive then `transformHead` will avoid that overhead during dev.
+
+#### Example: Adding `og:image` meta

 ```ts
 export default {
-  transformPageData(pageData) {
-    const canonicalUrl = `https://example.com/${pageData.relativePath}`
-      .replace(/index\.md$/, '')
-      .replace(/\.md$/, '.html')
+  async transformHead(context) {
+    if (context.page === '404.md') {
+      return
+    }

-    pageData.frontmatter.head ??= []
-    pageData.frontmatter.head.push([
-      'link',
-      { rel: 'canonical', href: canonicalUrl }
-    ])
+    // The implementation details of `generatePageImage` would depend
+    // on your requirements. Here we assume it generates a suitable
+    // image for each page and returns the image URL.
+    const imageUrl = await generatePageImage(context)
+    
+    return [[
+      'meta',
+      { name: 'og:image', content: imageUrl }
+    ]]
  }
 }
 ```

+Here we're assuming that the image URL is dynamic and time-consuming to generate. Using `transformHead` avoids that overhead during development.
+
+For simpler cases, it may be possible to use the [`head`](./frontmatter-config#head) setting in frontmatter, or [`transformPageData`](#transformpagedata).
+
 ### transformHtml

 - Type: `(code: string, id: string, context: TransformContext) => Awaitable<string | void>`
@ -721,3 +715,39 @@ interface TransformPageContext {
  siteConfig: SiteConfig
 }
 ```
+
+#### Example: Adding a `<meta name="og:title">`
+
+```ts
+export default {
+  transformPageData(pageData) {
+    const title = pageData.frontmatter.layout === 'home'
+      ? 'VitePress'
+      : `${pageData.title} | VitePress`
+
+    pageData.frontmatter.head ??= []
+    pageData.frontmatter.head.push([
+      'meta',
+      { name: 'og:title', content: title }
+    ])
+  }
+}
+```
+
+#### Example: Adding a canonical URL `<link>`
+
+```ts
+export default {
+  transformPageData(pageData) {
+    const canonicalUrl = `https://example.com/${pageData.relativePath}`
+      .replace(/index\.md$/, '')
+      .replace(/\.md$/, '.html')
+
+    pageData.frontmatter.head ??= []
+    pageData.frontmatter.head.push([
+      'link',
+      { rel: 'canonical', href: canonicalUrl }
+    ])
+  }
+}
+```