Auto-generating Frontmatter

This feature automatically generates frontmatter for each Markdown file.

What is Frontmatter?

Frontmatter is a metadata block written in YAML format at the very beginning of a Markdown file. You can think of it as the "ID card" or "configuration manual" of the Markdown file. It won't be rendered into the web page content directly, but is used to configure relevant parameters for the file.

Frontmatter is wrapped using three dashes (---) and located at the very start of the file:

frontmatter

---
title: Post Title
createTime: 2026/01/15 15:03:10
---

Here is the Markdown content...

The current theme supports auto-generated frontmatter including:

• title: Article title, generated based on the file name
• createTime: Article creation time, generated based on the file creation time
• permalink: Article permalink
  • Uses nanoid to generate an 8-character random string by default
  • Can be set to filepath to generate based on the file path

Rule Priority

The priority of frontmatter generation from highest to lowest is:

1. Manual Configuration: Frontmatter fields manually written in the Markdown file will not be automatically overwritten
2. Collection Configuration: Frontmatter rules configured for a specific collection in collections
3. Default Rules: Theme's built-in default generation rules

Configuration

Global Configuration

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    // autoFrontmatter: true, // Theme built-in configuration
    
autoFrontmatter
: {
      
title
: true, // Auto-generate title
      
createTime
: true, // Auto-generate creation time
      
permalink
: true, // Auto-generate permalink
    }
  })
})

.vuepress/plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'

export default 
defineThemeConfig
({
  // autoFrontmatter: true, // Theme built-in configuration
  
autoFrontmatter
: {
    
title
: true, // Auto-generate title
    
createTime
: true, // Auto-generate creation time
    
permalink
: true, // Auto-generate permalink
  }
})

Collection Configuration

You can configure autoFrontmatter separately for each collection.

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
collections
: [
      {
        
type
: 'doc',
        
dir
: 'guide',
        
title
: 'Guide',
        // autoFrontmatter: true, // Theme built-in configuration
        
autoFrontmatter
: {
          
title
: true, // Auto-generate title
          
createTime
: true, // Auto-generate creation time
          
permalink
: true, // Auto-generate permalink
        }
      }
    ]
  })
})

.vuepress/plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'

export default 
defineThemeConfig
({
  
collections
: [
    {
      
type
: 'doc',
      
dir
: 'guide',
      
title
: 'Guide',
      // autoFrontmatter: true, // Theme built-in configuration
      
autoFrontmatter
: {
        
title
: true, // Auto-generate title
        
createTime
: true, // Auto-generate creation time
        
permalink
: true, // Auto-generate permalink
      }
    }
  ]
})

Custom Processing Logic

Use transform(data, context, locale) to configure custom processing logic. data is the frontmatter data, context is the file context, and locale is the current language path.

• transform() can also be an async function, returning a Promise.
• transform() is applicable in both global configuration and collection configuration.

.vuepress/config.ts

import { defineUserConfig } from 'vuepress'
import { plumeTheme } from 'vuepress-theme-plume'

export default defineUserConfig({
  theme: plumeTheme({
    autoFrontmatter: {
      title: true, // Auto-generate title
      createTime: true, // Auto-generate creation time
      permalink: true, // Auto-generate permalink
      transform: (data, context, locale) => { // Custom transform
        // context.filePath // File absolute path
        // context.relativePath // File relative path, relative to source directory
        // context.content // Markdown content

        data.foo ??= 'foo'
        return data
      }
    }
  })
})

.vuepress/plume.config.ts

import { defineThemeConfig } from 'vuepress-theme-plume'

export default defineThemeConfig({
  autoFrontmatter: {
    title: true, // Auto-generate title
    createTime: true, // Auto-generate creation time
    permalink: true, // Auto-generate permalink
    transform: (data, context, locale) => { // Custom transform
      // context.filePath // File absolute path
      // context.relativePath // File relative path, relative to source directory
      // context.content // Markdown content

      data.foo ??= 'foo'
      return data
    }
  }
})

Interface

interface AutoFrontmatterContext {
  /**
   * File absolute path
   */
  filepath: string
  /**
   * File relative path
   */
  relativePath: string
  /**
   * File markdown content
   */
  content: string
}

interface AutoFrontmatterOptions {
  /**
   * Whether to auto-generate permalink
   *
   * - `false`: Do not auto-generate permalink
   * - `true`: Auto-generate permalink, using nanoid to generate an 8-digit random string
   * - `filepath`: Generate permalink based on file path
   *
   * @default true
   */
  permalink?: boolean | 'filepath'
  /**
   * Whether to auto-generate createTime
   *
   * Reads the file creation time by default. `createTime` is more precise to the second than VuePress's default `date` time.
   */
  createTime?: boolean
  /**
   * Whether to auto-generate title
   *
   * Reads the file name as the title by default.
   */
  title?: boolean

  /**
   * Custom frontmatter generation function
   *
   * - You should add new fields directly to `data`
   * - If a completely new `data` object is returned, it will overwrite the previous frontmatter
   * @param data Existing frontmatter on the page
   * @param context Context information of the current page
   * @param locale Current language path
   * @returns Returns the processed frontmatter
   */
  transform?: (data: AutoFrontmatterData, context: AutoFrontmatterContext, locale: string) => AutoFrontmatterData | Promise<AutoFrontmatterData>
}

Permalink

The theme uses nanoid to generate an 8-character random string as the file's permalink by default.

You can also configure permalink as 'filepath' to generate the permalink based on the file path. Please note, if your file path contains Chinese characters, the theme recommends installing pinyin-pro in your project to support converting Chinese to pinyin.

Changing permalink changes the URL of every existing article

The value of autoFrontmatter.permalink determines the access path of already-generated articles. After changing it, the URL of every article using an auto-generated link will change, and previously published links, external references and search-engine-indexed addresses will break (404). This is not reversible.

Be careful when changing it on a production site. If you only want to adjust the link of a few articles, specify permalink manually in that article's frontmatter to lock it — it takes precedence over the auto-generated link:

---
title: My Article
permalink: /custom/my-article/
---

npm

npm i pinyin-pro

pnpm

pnpm add pinyin-pro

yarn

yarn add pinyin-pro

.vuepress/config.ts

import { 
defineUserConfig
 } from 'vuepress'
import { 
plumeTheme
 } from 'vuepress-theme-plume'

export default 
defineUserConfig
({
  
theme
: 
plumeTheme
({
    
autoFrontmatter
: {
      
permalink
: 'filepath', 
    }
  })
})

.vuepress/plume.config.ts

import { 
defineThemeConfig
 } from 'vuepress-theme-plume'

export default 
defineThemeConfig
({
  
autoFrontmatter
: {
    
permalink
: 'filepath', 
  }
})

Example:

docs

blog

service.md

capital.md

docs/blog/service.md

---
title: Service
permalink: /blog/service/
---

docs/blog/capital.md

---
title: Capital
permalink: /blog/capital/
---

You probably noticed that in the example, the permalink for the capital.md file is /blog/capital/, which is incorrect. This is because pinyin-pro's default dictionary cannot accurately identify polyphonic characters. If you need a more precise conversion result,you can manually install @pinyin-pro/data, and the theme will automatically load this dictionary to improve accuracy.

npm

npm i @pinyin-pro/data

pnpm

pnpm add @pinyin-pro/data

yarn

yarn add @pinyin-pro/data

docs/blog/capital.md

---
title: Capital
permalink: /blog/capital/
---

Contributors

pengzhanbo

Changelog

10/11/26, 4:27 AM

View All Changelog

• 60619-docs: improve docs (#1069)on 10/11/26
• 0daf2-docs: improve docs (#929)on 7/15/26
• 97a5b-docs: fix typoon 3/8/26
• a3d8e-feat(theme): add filepath permalink support for auto frontmatter, #815 (#822)on 1/19/26

Edit this page

Previous pageSidebar

Next pageInternationalization