The filename customization API allows you to customize the filename of a document based on its content. This is useful when you do not want your editors to have to worry about the filename of a document.

A couple things to keep in mind when customizing the filename:

• Filename can not contain any spaces
• Filename must contain only a-z, A-Z, 0-9, -, _, ., or /.
• Filename must be unique within the collection
• If the filename starts with / it will be treated as an absolute path relative to the collection root
  • Example: /foo/bar/blog-post will be saved as <MyCollectionPath>/post/blog-post.md
• If the filename does not start with / it will be treated as a relative to your current folder
  • Example: bar/blog-post will be saved as <MyCollectionPath>/<CurrentDirectory>/bar/blog-post.md

Definition

Usage

To use the filename customization API, you need to pass a slugify function that allows you to customize the filename of a document based on its content.

Example with slugify and disabled

export default defineConfig({
  //...
  schema: {
    collections: [
      {
        label: 'Blog Posts',
        name: 'post',
        path: 'content/post',
        format: 'md',
        ui: {
          filename: {
            // if disabled, the editor can not edit the filename
            readonly: true,
            // Example of using a custom slugify function
            slugify: (values) => {
              // Values is an object containing all the values of the form. In this case it is {title?: string, topic?: string}
              return `${values?.topic || 'no-topic'}-${values?.title
                ?.toLowerCase()
                .replace(/ /g, '-')}`
            },
          },
        },
        fields: [
          {
            type: 'string',
            label: 'Title',
            name: 'title',
          },
          {
            type: 'string',
            label: 'Topic',
            name: 'topic',
            options: ['programming', 'blacksmithing'],
          },
        ],
      },
    ],
  },
})

Example with default slugify

If no slugify function is provided and there is a field with isTItle: true. A default slugify function will be used that strips out every non-alphanumeric character and replaces spaces with dashes.

export default defineConfig({
  //...
  schema: {
    collections: [
      {
        label: 'Blog Posts',
        name: 'post',
        path: 'content/post',
        format: 'md',
        fields: [
          {
            type: 'string',
            label: 'Title',
            name: 'title',
            // If no slugify function is provided, then by default the "title" field will be used to generate the filename
            isTitle: true,
            required: true,
          },
          {
            type: 'string',
            label: 'Topic',
            name: 'topic',
            options: ['programming', 'blacksmithing'],
          },
        ],
      },
    ],
  },
})