Configuring head tags in VitePress

Managing metadata is crucial for web presence and SEO. VitePress offers several powerful ways to configure <head> tags, from static site-wide settings to dynamic, page-specific modifications. This guide provides a comprehensive overview of how to effectively manage your head configurations in VitePress, ensuring your site's metadata is precisely tailored to your needs.

Frontmatter

This section details how to configure page-specific metadata using head within the frontmatter. This allows you to set unique Open Graph (OG) titles or other meta tags for individual pages.

---
head:
  - ['meta', { property: 'og:title', content: 'title' }]
---

The provided example demonstrates setting an og:title meta tag. This configuration is applied on a per-page basis, overriding any site-wide settings for the specified meta property.

Config: `head` option

Here, we look at configuring site-wide metadata using the head option in your VitePress configuration file. This is useful for applying common meta tags across your entire site.

export default {
  head: [
    ['meta', { property: 'og:title', content: 'title' }]
  ]
}

This configuration snippet shows how to set a global og:title meta tag. Any meta tags defined here will be applied to all pages on your site unless overridden by page-specific frontmatter.

Config: `transformHead()` function

The transformHead() function provides a way to dynamically modify the head tags during the build process of your VitePress site. This is particularly useful for generating meta tags based on the current page's context.

export default {
  transformHead(context) {
    return [
      ['meta', { property: 'og:title', content: context.title }]
    ]
  }
}

In this example, transformHead() is used to set the og:title dynamically, using the context.title of the page being built.

WARNING

This function runs only at build time, not during development.

Config: `transformPageData()` function

The transformPageData() function offers the most flexible way to modify page data, including head configurations, and is applied during both development and build times. It allows you to programmatically manipulate the data for each page.

export default {
  transformPageData(pageData) {
    pageData.frontmatter.head ??= []
    pageData.frontmatter.head.push(['meta', { property: 'og:title', content: pageData.title }])
  }
}

This code snippet illustrates how to add an og:title meta tag to the head array within pageData.frontmatter. It ensures that pageData.frontmatter.head exists before pushing the new meta tag, making it a robust solution for dynamically adding page-specific metadata.

Example: Injecting Google Analytics tags

A common use case is the injection of analytics tracking codes, such as Google Analytics. The transformHead() function is a powerful tool for integrating third-party scripts and services that require placement within the <head> of your HTML document.

The following example demonstrates how to use transformHead() to add the necessary Google Analytics global site tag (gtag.js) to every page of your VitePress site during the build process. Remember to replace "TAG_ID" with your actual Google Analytics Measurement ID.

export default {
  transformHead() {
    return [
      [
        'script',
        {
          async: '',
          src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID',
        },
      ],
      [
        'script',
        {},
        `
        window.dataLayer = window.dataLayer || [];
        function gtag() { dataLayer.push(arguments); }
        gtag("js", new Date());
        gtag("config", "TAG_ID");
        `,
      ],
    ]
  }
}

By placing these scripts within transformHead(), you ensure that Google Analytics is properly initialized and can track user interactions on your deployed VitePress site. This method is ideal for static site generators like VitePress, as the scripts are embedded directly into the HTML at build time, rather than requiring client-side JavaScript to modify the DOM after the page loads.

Configuring head tags in VitePress ​

Frontmatter ​

Config: head option ​

Config: transformHead() function ​

Config: transformPageData() function ​