Collection Sources

Nuxt Content provides several ways to import content files into your collection. You can configure the source by using the source property within defineCollection:

import { defineCollection, defineContentConfig } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      source: '**',
      type: 'page'
    })
  }
})

source

The source property can be defined as either a string (following a glob pattern) or an object, allowing more detailed source configuration for your target directory and files within the content folder.

Example:

• source: '**' includes all files within the content directory and its subdirectories.
• source: '**/*.md'includes all Markdown files within the content directory and its subdirectories.
• source: 'docs/**/*.yml' includes all YML files within the content/docs and its subdirectories.
• source: '**/*.{json,yml}' includes JSON or YML file within the content directory and all its subdirectories.
• source: '*.json' includes only JSON files located directly within the content directory, excluding any subdirectories.

include (required)

Glob pattern of your target repository and files in the content folder.

exclude

Glob patterns to exclude content from the import.

prefix

This configuration only applied for page type with 1-to-1 relationship between content files and pages on your site.

It represents the path prefix (base URL) of the corresponding page on the website.

By default, module extracts the static prefix of source(or source.include) and uses it as a prefix for content paths. For example, if you define /en/** source, module will auto-fill the prefix with /en. You can manually provide a prefix to override this behavior. The prefix can be removed by setting prefix: '/' in the collection source.

defineCollection({
  type: "page",
  source: {
    include: "en/**",
    exclude: ["en/index.md"],
    prefix: '/'
  }
})

cwd

Root directory for content matching.

Example:

If you want to include files from a folder outside the content directory, set the absolute path of that folder to the cwd property.

source: {
  cwd: path.resolve('packages/my-pkg/docs'),
  include: '**/*.md',
}

repository

External source representing a remote git repository URL (e.g., https://github.com/nuxt/content), or an object containing Git branch / tag information, or optionally authentication

When defining an external source you must also define the include option. include pattern is essential for the module to know which files to use for the collection.

import { defineCollection, defineContentConfig } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: {
        repository: 'https://github.com/nuxt/content',
        include: 'docs/content/**',
      },
    })
  }
})

branch / tag

This option allows for cloning a Git repository by its tag or branch.

Example: If you want to clone by a tag, make the repository attribute an object, with the url of your repository, and set the tag attribute.

import { defineCollection, defineContentConfig } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: {
        repository: {
          url: 'https://github.com/nuxt/content',
          tag: 'v1'
        },
        include: 'docs/content/**',
      },
    })
  }
})

Example:

If you want to clone by a remote branch, make the repository attribute an object, with the url of your repository, and set the branch attribute.

import { defineCollection, defineContentConfig } from '@nuxt/content'

export default defineContentConfig({
  collections: {
    docs: defineCollection({
      type: 'page',
      source: {
        repository: {
          url: 'https://github.com/nuxt/content',
          branch: 'dev'
        },
        include: 'docs/content/**',
      },
    })
  }
})

auth

This option allows for basic and token-based authentication for Git repositories.

Example:

If you want to use basic authentication (e.g. for BitBucket repositories), you can use:

defineCollection({
  type: 'page',
  source: {
    repository: {
      url: 'https://bitbucket.org/username/repo',
      auth: {
        username: 'username',
        password: 'password',
      },
    },
  },
})

Example:

If you need to use authentication tokens (e.g. for Github, Gitlab, some Forgejo providers), you can do the following:

defineCollection({
  type: 'page',
  source: {
    repository: {
      url: 'https://github.com/username/repo',
      auth: {
        username: 'username',
        token: 'password',
      },
    },
  },
})