VitePress Data Loading

VitePress provides a mechanism to load data at build time and access that data in client-side components. This is very useful for fetching data from local files (such as JSON, YAML) or remote APIs and generating static content.

This functionality is implemented by creating .data.js or .data.ts files.

Basic Usage

1. Create Data Loader File

   Create a .data.js file with the same name as your Markdown file anywhere in your docs directory. For example, if you have a members.md, you can create a members.data.js.

   .
   └── docs
       ├── members.md
       └── members.data.js

2. Write Data Loading Script

   In the .data.js file, you need to export a load function. This function is executed during build time in the Node.js environment.

   // docs/members.data.js
   import { createContentLoader } from 'vitepress'
   
   export default createContentLoader('path/to/your/data/*.md', {
     // ... options
   })

   createContentLoader is a helper function for loading and transforming a set of Markdown files. The first parameter is a glob pattern used to match the files you want to load.

   You can also export a custom load function to fetch data from anywhere:

   // docs/api.data.js
   export default {
     async load() {
       const response = await fetch('https://api.example.com/items');
       const data = await response.json();
       return data; // The returned data will be available on the client side
     }
   }

Accessing Data in Components

Once you've defined the data loader file, VitePress will automatically handle data loading and passing. You can directly access this data in the .md file with the same name as the data file.

Data is exposed through the useData composable function.

<!-- docs/members.md -->
<script setup>
import { useData } from 'vitepress'

// data is loaded from members.data.js
const { data: members } = useData()
</script>

# Team Members

<ul>
  <li v-for="member of members">
    <a :href="member.url">{{ member.frontmatter.name }}</a>
  </li>
</ul>

In this example, members.data.js uses createContentLoader to load a series of member Markdown files. In members.md, we retrieved this member data through useData and rendered a list using v-for.

How It Works

1. Build Time (Node.js): VitePress scans your files, finds all .data.js files, and executes the load function in each file, serializing the returned data into JSON.
2. Client Side (Browser): When a user visits a page, VitePress asynchronously loads the corresponding page's data as needed. The useData composable returns this pre-loaded data.

Caching

The result of the load function will be cached. If you want to reload data every time a file changes in development mode, you can set the watch option.

// docs/members.data.js
import { createContentLoader } from 'vitepress'

export default createContentLoader('members/*.md', {
  watch: ['path/to/your/data/*.md'], // Watch for file changes
})

Data loading is a powerful feature of VitePress that allows you to combine static content with dynamic data sources to create more complex, data-driven websites while maintaining the performance advantages of static sites.