vitepress Documentation

1. Project Overview & Quickstart (vuejs/vitepress) Copy Chapter

File: README.md Copy Chapter

VitePress 📝💨

VitePress is a Vue-powered static site generator and a spiritual successor to VuePress, built on top of Vite.

Documentation Copy Chapter

To check out docs, visit vitepress.dev.

Changelog Copy Chapter

Detailed changes for each release are documented in the CHANGELOG.

Contribution Copy Chapter

Please make sure to read the Contributing Guide before making a pull request.

License Copy Chapter

MIT

Copyright (c) 2019-present, Yuxi (Evan) You

Special Thanks Copy Chapter

This project would not be possible without the support of these amazing companies and tools.

File: docs/en/guide/asset-handling.md Copy Chapter

Asset Handling

Referencing Static Assets Copy Chapter

All Markdown files are compiled into Vue components and processed by Vite. You can, and should, reference any assets using relative URLs:

You can reference static assets in your markdown files, your *.vue components in the theme, styles and plain .css files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's file-loader.

Common image, media, and font filetypes are detected and included as assets automatically.

::: tip Linked files are not treated as assets
PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the public directory of your project.
:::

All referenced assets, including those using absolute paths, will be copied to the output directory with a hashed file name in the production build. Never-referenced assets will not be copied. Image assets smaller than 4kb will be base64 inlined - this can be configured via the vite config option.

All static path references, including absolute paths, should be based on your working directory structure.

The Public Directory Copy Chapter

Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include robots.txt, favicons, and PWA icons.

You can place these files in the public directory under the source directory. For example, if your project root is ./docs and using default source directory location, then your public directory will be ./docs/public.

Assets placed in public will be copied to the root of the output directory as-is.

Note that you should reference files placed in public using root absolute path - for example, public/icon.png should always be referenced in source code as /icon.png.

Base URL Copy Chapter

If your site is deployed to a non-root URL, you will need to set the base option in .vitepress/config.js. For example, if you plan to deploy your site to https://foo.github.io/bar/, then base should be set to '/bar/' (it should always start and end with a slash).

All your static asset paths are automatically processed to adjust for different base config values. For example, if you have an absolute reference to an asset under public in your markdown:

You do not need to update it when you change the base config value in this case.

However, if you are authoring a theme component that links to assets dynamically, e.g. an image whose src is based on a theme config value:

In this case it is recommended to wrap the path with the withBase helper provided by VitePress:

<script setup>
import { withBase, useData } from 'vitepress'

const { theme } = useData()
</script>

<template>
  
</template>

File: docs/en/guide/cms.md Copy Chapter

outline: deep Copy Chapter

Connecting to a CMS

General Workflow Copy Chapter

Connecting VitePress to a CMS will largely revolve around Dynamic Routes. Make sure to understand how it works before proceeding.

Since each CMS will work differently, here we can only provide a generic workflow that you will need to adapt to your specific scenario.

1. If your CMS requires authentication, create an .env file to store your API tokens and load it so:

   js Copy

   // posts/[id].paths.js
   import { loadEnv } from 'vitepress'
   
   const env = loadEnv('', process.cwd())

2. Fetch the necessary data from the CMS and format it into proper paths data:

   js Copy

   export default {
     async paths() {
       // use respective CMS client library if needed
       const data = await (await fetch('https://my-cms-api', {
         headers: {
           // token if necessary
         }
       })).json()
   
       return data.map(entry => {
         return {
           params: { id: entry.id, /* title, authors, date etc. */ },
           content: entry.content
         }
       })
     }
   }

3. Render the content in the page:

   md Copy

   # {{ $params.title }}
   
   - by {{ $params.author }} on {{ $params.date }}

Integration Guides Copy Chapter

If you have written a guide on integrating VitePress with a specific CMS, please use the "Edit this page" link below to submit it here!

File: docs/en/guide/custom-theme.md Copy Chapter

Using a Custom Theme

Theme Resolving Copy Chapter

You can enable a custom theme by creating a .vitepress/theme/index.js or .vitepress/theme/index.ts file (the "theme entry file"):

.
├─ docs                # project root
│  ├─ .vitepress
│  │  ├─ theme
│  │  │  └─ index.js   # theme entry
│  │  └─ config.js     # config file
│  └─ index.md
└─ package.json

VitePress will always use the custom theme instead of the default theme when it detects presence of a theme entry file. You can, however, extend the default theme to perform advanced customizations on top of it.

Theme Interface Copy Chapter

A VitePress custom theme is defined as an object with the following interface:

interface Theme {
  /**
   * Root layout component for every page
   * @required
   */
  Layout: Component
  /**
   * Enhance Vue app instance
   * @optional
   */
  enhanceApp?: (ctx: EnhanceAppContext) => Awaitable<void>
  /**
   * Extend another theme, calling its `enhanceApp` before ours
   * @optional
   */
  extends?: Theme
}

interface EnhanceAppContext {
  app: App // Vue app instance
  router: Router // VitePress router instance
  siteData: Ref<SiteData> // Site-level metadata
}

The theme entry file should export the theme as its default export:

// You can directly import Vue files in the theme entry
// VitePress is pre-configured with @vitejs/plugin-vue.
import Layout from './Layout.vue'

export default {
  Layout,
  enhanceApp({ app, router, siteData }) {
    // app.component(...)
    // app.use(...)
  }
}

The enhanceApp hook allows you to access the Vue app instance and other runtime data, which can be used to register global components, integrate with Vue libraries, etc.

The router value is the same VitePress router instance returned by useRouter(). To listen for route changes, assign handlers on the router:

export default {
  enhanceApp({ router }) {
    router.onBeforeRouteChange = (to) => {
      console.log('navigating to', to)
    }

    router.onAfterRouteChange = (to) => {
      console.log('navigated to', to)
    }
  }
}

Return false from onBeforeRouteChange or onBeforePageLoad to cancel navigation.

The default export is the only contract for a custom theme, and only the Layout property is required. So technically, a VitePress theme can be as simple as a single Vue component.

Inside your layout component, it works just like a normal Vite + Vue 3 application. Do note the theme also needs to be SSR-compatible.

Building a Layout Copy Chapter

The most basic layout component needs to contain a <Content /> component:

<template>
  <h1>Custom Layout!</h1>

  
  <Content />
</template>

The above layout simply renders every page's markdown as HTML. The first improvement we can add is to handle 404 errors:

<script setup>
import { useData } from 'vitepress'
const { page } = useData()
</script>

<template>
  <h1>Custom Layout!</h1>

  
    Custom 404 page!
  
  <Content v-else />
</template>

The useData() helper provides us with all the runtime data we need to conditionally render different layouts. One of the other data we can access is the current page's frontmatter. We can leverage this to allow the end user to control the layout in each page. For example, the user can indicate the page should use a special home page layout with:

---
layout: home
---

And we can adjust our theme to handle this:

<script setup>
import { useData } from 'vitepress'
const { page, frontmatter } = useData()
</script>

<template>
  <h1>Custom Layout!</h1>

  
    Custom 404 page!
  
  
    Custom home page!
  
  <Content v-else />
</template>

You can, of course, split the layout into more components:

<script setup>
import { useData } from 'vitepress'
import NotFound from './NotFound.vue'
import Home from './Home.vue'
import Page from './Page.vue'

const { page, frontmatter } = useData()
</script>

<template>
  <h1>Custom Layout!</h1>

  <NotFound v-if="page.isNotFound" />
  <Home v-if="frontmatter.layout === 'home'" />
   
</template>

Consult the Runtime API Reference for everything available in theme components. In addition, you can leverage Build-Time Data Loading to generate data-driven layout - for example, a page that lists all blog posts in the current project.

Distributing a Custom Theme Copy Chapter

The easiest way to distribute a custom theme is by providing it as a template repository on GitHub.

If you wish to distribute the theme as an npm package, follow these steps:

1. Export the theme object as the default export in your package entry.

2. If applicable, export your theme config type definition as ThemeConfig.

3. If your theme requires adjusting the VitePress config, export that config under a package sub-path (e.g. my-theme/config) so the user can extend it.

4. Document the theme config options (both via config file and frontmatter).

5. Provide clear instructions on how to consume your theme (see below).

Consuming a Custom Theme Copy Chapter

To consume an external theme, import and re-export it from the custom theme entry:

import Theme from 'awesome-vitepress-theme'

export default Theme

If the theme needs to be extended:

import Theme from 'awesome-vitepress-theme'

export default {
  extends: Theme,
  enhanceApp(ctx) {
    // ...
  }
}

If the theme requires special VitePress config, you will need to also extend it in your own config:

import baseConfig from 'awesome-vitepress-theme/config'

export default {
  // extend theme base config (if needed)
  extends: baseConfig
}

Finally, if the theme provides types for its theme config:

import baseConfig from 'awesome-vitepress-theme/config'
import { defineConfig } from 'vitepress'
import type { ThemeConfig } from 'awesome-vitepress-theme'

export default defineConfig({
  extends: baseConfig,
  themeConfig: {
    // Type is `ThemeConfig`
  }
})

File: docs/en/guide/data-loading.md Copy Chapter

Build-Time Data Loading

VitePress provides a feature called data loaders that allows you to load arbitrary data and import it from pages or components. The data loading is executed only at build time: the resulting data will be serialized as JSON in the final JavaScript bundle.

Data loaders can be used to fetch remote data, or generate metadata based on local files. For example, you can use data loaders to parse all your local API pages and automatically generate an index of all API entries.

Basic Usage Copy Chapter

A data loader file must end with either .data.js or .data.ts. The file should provide a default export of an object with the load() method:

export default {
  load() {
    return {
      hello: 'world'
    }
  }
}

The loader module is evaluated only in Node.js, so you can import Node APIs and npm dependencies as needed.

You can then import data from this file in .md pages and .vue components using the data named export:

<script setup>
import { data } from './example.data.js'
</script>

{{ data }}

Output:

{
  "hello": "world"
}

You'll notice the data loader itself does not export the data. It is VitePress calling the load() method behind the scenes and implicitly exposing the result via the data named export.

This works even if the loader is async:

export default {
  async load() {
    // fetch remote data
    return (await fetch('...')).json()
  }
}

Data from Local Files Copy Chapter

When you need to generate data based on local files, you should use the watch option in the data loader so that changes made to these files can trigger hot updates.

The watch option is also convenient in that you can use glob patterns to match multiple files. The patterns can be relative to the loader file itself, and the load() function will receive the matched files as absolute paths.

The following example shows loading CSV files and transforming them into JSON using csv-parse. Because this file only executes at build time, you will not be shipping the CSV parser to the client!

import fs from 'node:fs'
import { parse } from 'csv-parse/sync'

export default {
  watch: ['./data/*.csv'],
  load(watchedFiles) {
    // watchedFiles will be an array of absolute paths of the matched files.
    // generate an array of blog post metadata that can be used to render
    // a list in the theme layout
    return watchedFiles.map((file) => {
      return parse(fs.readFileSync(file, 'utf-8'), {
        columns: true,
        skip_empty_lines: true
      })
    })
  }
}

`createContentLoader` Copy Chapter

When building a content focused site, we often need to create an "archive" or "index" page: a page where we list all available entries in our content collection, for example blog posts or API pages. We can implement this directly with the data loader API, but since this is such a common use case, VitePress also provides a createContentLoader helper to simplify this:

import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', /* options */)

The helper takes a glob pattern relative to the source directory, and returns a { watch, load } data loader object that can be used as the default export in a data loader file. It also implements caching based on file modified timestamps to improve dev performance.

Note the loader only works with Markdown files - matched non-Markdown files will be skipped.

The loaded data will be an array with the type of ContentData[]:

interface ContentData {
  // mapped URL for the page. e.g. /posts/hello.html (does not include base)
  // manually iterate or use custom `transform` to normalize the paths
  url: string
  // frontmatter data of the page
  frontmatter: Record<string, any>

  // the following are only present if relevant options are enabled
  // we will discuss them below
  src: string | undefined
  html: string | undefined
  excerpt: string | undefined
}

By default, only url and frontmatter are provided. This is because the loaded data will be inlined as JSON in the client bundle, so we need to be cautious about its size. Here's an example using the data to build a minimal blog index page:

<script setup>
import { data as posts } from './posts.data.js'
</script>

<template>
  <h1>All Blog Posts</h1>
  
    <li v-for="post of posts">
      <a :href="post.url">{{ post.frontmatter.title }}</a>
      by {{ post.frontmatter.author }}
    </li>
  
</template>

Options Copy Section

The default data may not suit all needs - you can opt-in to transform the data using options:

import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  includeSrc: true, // include raw markdown source?
  render: true,     // include rendered full page HTML?
  excerpt: true,    // include excerpt?
  transform(rawData) {
    // map, sort, or filter the raw data as you wish.
    // the final result is what will be shipped to the client.
    return rawData.sort((a, b) => {
      return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date)
    }).map((page) => {
      page.src     // raw markdown source
      page.html    // rendered full page HTML
      page.excerpt // rendered excerpt HTML (content above first `---`)
      return {/* ... */}
    })
  }
})

Check out how it is used in the Vue.js blog.

The createContentLoader API can also be used inside build hooks:

export default {
  async buildEnd() {
    const posts = await createContentLoader('posts/*.md').load()
    // generate files based on posts metadata, e.g. RSS feed
  }
}

Types

interface ContentOptions<T = ContentData[]> {
  /**
   * Include src?
   * @default false
   */
  includeSrc?: boolean

  /**
   * Render src to HTML and include in data?
   * @default false
   */
  render?: boolean

  /**
   * If `boolean`, whether to parse and include excerpt? (rendered as HTML)
   *
   * If `function`, control how the excerpt is extracted from the content.
   *
   * If `string`, define a custom separator to be used for extracting the
   * excerpt. Default separator is `---` if `excerpt` is `true`.
   *
   * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt
   * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator
   *
   * @default false
   */
  excerpt?:
    | boolean
    | ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void)
    | string

  /**
   * Transform the data. Note the data will be inlined as JSON in the client
   * bundle if imported from components or markdown files.
   */
  transform?: (data: ContentData[]) => T | Promise<T>
}

Typed Data Loaders Copy Chapter

When using TypeScript, you can type your loader and data export like so:

import { defineLoader } from 'vitepress'

export interface Data {
  // data type
}

declare const data: Data
export { data }

export default defineLoader({
  // type checked loader options
  watch: ['...'],
  async load(): Promise<Data> {
    // ...
  }
})

Configuration Copy Chapter

To get the configuration information inside a loader, you can use some code like this:

import type { SiteConfig } from 'vitepress'

const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG

File: docs/en/guide/deploy.md Copy Chapter

outline: deep Copy Chapter

Deploy Your VitePress Site

The following guides are based on some shared assumptions:

• The VitePress site is inside the docs directory of your project.

• You are using the default build output directory (.vitepress/dist).

• VitePress is installed as a local dependency in your project, and you have set up the following scripts in your package.json:

  json [package.json] Copy

  {
    "scripts": {
      "docs:build": "vitepress build docs",
      "docs:preview": "vitepress preview docs"
    }
  }

Build and Test Locally Copy Chapter

1. Run this command to build the docs:

   sh Copy

   $ npm run docs:build

2. Once built, preview it locally by running:

   sh Copy

   $ npm run docs:preview

   The preview command will boot up a local static web server that will serve the output directory .vitepress/dist at http://localhost:4173. You can use this to make sure everything looks good before pushing to production.

3. You can configure the port of the server by passing --port as an argument.

   json Copy

   {
     "scripts": {
       "docs:preview": "vitepress preview docs --port 8080"
     }
   }

   Now the docs:preview method will launch the server at http://localhost:8080.

Setting a Public Base Path Copy Chapter

By default, we assume the site is going to be deployed at the root path of a domain (/). If your site is going to be served at a sub-path, e.g. https://mywebsite.com/blog/, then you need to set the base option to '/blog/' in the VitePress config.

Example: If you're using Github (or GitLab) Pages and deploying to user.github.io/repo/, then set your base to /repo/.

HTTP Cache Headers Copy Chapter

If you have control over the HTTP headers on your production server, you can configure cache-control headers to achieve better performance on repeated visits.

The production build uses hashed file names for static assets (JavaScript, CSS and other imported assets not in public). If you inspect the production preview using your browser devtools' network tab, you will see files like app.4f283b18.js.

This 4f283b18 hash is generated from the content of this file. The same hashed URL is guaranteed to serve the same file content - if the contents change, the URLs change too. This means you can safely use the strongest cache headers for these files. All such files will be placed under assets/ in the output directory, so you can configure the following header for them:

Cache-Control: max-age=31536000,immutable

::: details Example Netlify _headers file

/assets/*
  cache-control: max-age=31536000
  cache-control: immutable

Note: the _headers file should be placed in the public directory - in our case, docs/public/_headers - so that it is copied verbatim to the output directory.

Netlify custom headers documentation

:::

::: details Example Vercel config in vercel.json

{
  "headers": [
    {
      "source": "/assets/(.*)",
      "headers": [
        {
          "key": "Cache-Control",
          "value": "max-age=31536000, immutable"
        }
      ]
    }
  ]
}

Note: the vercel.json file should be placed at the root of your repository.

Vercel documentation on headers config

:::

Platform Guides Copy Chapter

Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#generic} Copy Section

Set up a new project and change these settings using your dashboard:

• Build Command: npm run docs:build
• Output Directory: docs/.vitepress/dist
• Node Version: 20 (or above)

::: warning
Don't enable options like Auto Minify for HTML code. It will remove comments from output which have meaning to Vue. You may see hydration mismatch errors if they get removed.
:::

GitHub Pages Copy Section

1. Create a file named deploy.yml inside .github/workflows directory of your project with some content like this:

   text Copy

/* Detailed source-code truncated for AI context efficiency. */

::: warning
   Make sure the `base` option in your VitePress is properly configured. See [Setting a Public Base Path](#setting-a-public-base-path) for more details.
   :::

2. In your repository's settings under "Pages" menu item, select "GitHub Actions" in "Build and deployment > Source".

3. Push your changes to the `main` branch and wait for the GitHub Actions workflow to complete. You should see your site deployed to `https://.github.io/[repository]/` or `https://<custom-domain>/` depending on your settings. Your site will automatically be deployed on every push to the `main` branch.

### GitLab Pages

1. Set `outDir` in VitePress config to `../public`. Configure `base` option to `'/<repository>/'` if you want to deploy to `https://.gitlab.io/<repository>/`. You don't need `base` if you're deploying to custom domain, user or group pages, or have "Use unique domain" setting enabled in GitLab.

2. Create a file named `.gitlab-ci.yml` in the root of your project with the content below. This will build and deploy your site whenever you make changes to your content:

   ```yaml [.gitlab-ci.yml]
   image: node:24
   pages:
     cache:
       paths:
         - node_modules/
     script:
       # - apk add git # Uncomment this if you're using small docker images like alpine and have lastUpdated enabled
       - npm install
       - npm run docs:build
     artifacts:
       paths:
         - public
     only:
       - main

Azure Copy Section

1. Follow the official documentation.

2. Set these values in your configuration file (and remove the ones you don't require, like api_location):

   • app_location: /
   • output_location: docs/.vitepress/dist
   • app_build_command: npm run docs:build

CloudRay Copy Section

You can deploy your VitePress project with CloudRay by following these instructions.

Firebase Copy Section

1. Create firebase.json and .firebaserc at the root of your project:

   firebase.json:

   json [firebase.json] Copy

   {
     "hosting": {
       "public": "docs/.vitepress/dist",
       "ignore": []
     }
   }

   .firebaserc:

   json [.firebaserc] Copy

   {
     "projects": {
       "default": "<YOUR_FIREBASE_ID>"
     }
   }

2. After running npm run docs:build, run this command to deploy:

   sh Copy

   firebase deploy

Heroku Copy Section

1. Follow documentation and guide given in heroku-buildpack-static.

2. Create a file called static.json in the root of your project with the below content:

   json [static.json] Copy

   {
     "root": "docs/.vitepress/dist"
   }

Hostinger Copy Section

You can deploy your VitePress project with Hostinger by following these instructions. While configuring build settings, choose VitePress as the framework and adjust the root directory to ./docs.

Stormkit Copy Section

You can deploy your VitePress project to Stormkit by following these instructions.

Surge Copy Section

After running npm run docs:build, run this command to deploy to Surge:

npx surge docs/.vitepress/dist

harvis Copy Section

After running npm run docs:build, run this command to deploy to harvis:

npx harvis docs/.vitepress/dist

nginx Copy Section

Here is a example of an nginx server block configuration. This setup includes gzip compression for common text-based assets, rules for serving your VitePress site's static files with proper caching headers as well as handling cleanUrls: true.

map $uri $cache_control {
    ~^/assets/  "public, max-age=31536000, immutable";
    default     "no-cache";
}

server {
    listen 8080;
    listen [::]:8080;
    server_name _;

    root /usr/share/nginx/html;
    index index.html;
    charset utf-8;
    server_tokens off;

    absolute_redirect off;

    gzip on;
    gzip_vary on;
    gzip_comp_level 5;
    gzip_min_length 1024;
    gzip_types
        application/javascript
        application/json
        application/manifest+json
        image/svg+xml
        text/css
        text/javascript
        text/plain;

    add_header Cache-Control $cache_control always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header Referrer-Policy "strict-origin-when-cross-origin" always;

    location / {
        try_files $uri $uri.html $uri/index.html =404;
    }

    location ~ ^(?.+)/$ {
        if (-f $document_root$page.html) {
            return 301 $page$is_args$args;
        }
        try_files $page/index.html =404;
    }

    error_page 404 /404.html;
}

File: docs/en/guide/extending-default-theme.md Copy Chapter

outline: deep Copy Chapter

Extending the Default Theme

VitePress' default theme is optimized for documentation, and can be customized. Consult the Default Theme Config Overview for a comprehensive list of options.

However, there are a number of cases where configuration alone won't be enough. For example:

1. You need to tweak the CSS styling;
2. You need to modify the Vue app instance, for example to register global components;
3. You need to inject custom content into the theme via layout slots.

These advanced customizations will require using a custom theme that "extends" the default theme.

::: tip
Before proceeding, make sure to first read Using a Custom Theme to understand how custom themes work.
:::

Customizing CSS Copy Chapter

The default theme CSS is customizable by overriding root level CSS variables:

import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default DefaultTheme

/* .vitepress/theme/custom.css */
:root {
  --vp-c-brand-1: #646cff;
  --vp-c-brand-2: #747bff;
}

See default theme CSS variables that can be overridden.

Using Different Fonts Copy Chapter

VitePress uses Inter as the default font, and will include the fonts in the build output. The font is also auto preloaded in production. However, this may not be desirable if you want to use a different main font.

To avoid including Inter in the build output, import the theme from vitepress/theme-without-fonts instead:

import DefaultTheme from 'vitepress/theme-without-fonts'
import './my-fonts.css'

export default DefaultTheme

/* .vitepress/theme/my-fonts.css */
:root {
  --vp-font-family-base: /* normal text font */
  --vp-font-family-mono: /* code font */
}

::: warning
If you are using optional components like the Team Page components, make sure to also import them from vitepress/theme-without-fonts!
:::

If your font is a local file referenced via @font-face, it will be processed as an asset and included under .vitepress/dist/assets with hashed filename. To preload this file, use the transformHead build hook:

export default {
  transformHead({ assets }) {
    // adjust the regex accordingly to match your font
    const myFontFile = assets.find(file => /font-name\.[\w-]+\.woff2/.test(file))
    if (myFontFile) {
      return [
        [
          'link',
          {
            rel: 'preload',
            href: myFontFile,
            as: 'font',
            type: 'font/woff2',
            crossorigin: ''
          }
        ]
      ]
    }
  }
}

Registering Global Components Copy Chapter

import DefaultTheme from 'vitepress/theme'

/** @type {import('vitepress').Theme} */
export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // register your custom global components
    app.component('MyGlobalComponent' /* ... */)
  }
}

If you're using TypeScript:

import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // register your custom global components
    app.component('MyGlobalComponent' /* ... */)
  }
} satisfies Theme

Since we are using Vite, you can also leverage Vite's glob import feature to auto register a directory of components.

Layout Slots Copy Chapter

The default theme's <Layout/> component has a few slots that can be used to inject content at certain locations of the page. Here's an example of injecting a component into the before outline:

import DefaultTheme from 'vitepress/theme'
import MyLayout from './MyLayout.vue'

export default {
  extends: DefaultTheme,
  // override the Layout with a wrapper component that
  // injects the slots
  Layout: MyLayout
}

<script setup>
import DefaultTheme from 'vitepress/theme'

const { Layout } = DefaultTheme
</script>

<template>
  <Layout>
    <template #aside-outline-before>
      My custom sidebar top content
    </template>
  </Layout>
</template>

Or you could use render function as well.

import { h } from 'vue'
import DefaultTheme from 'vitepress/theme'
import MyComponent from './MyComponent.vue'

export default {
  extends: DefaultTheme,
  Layout() {
    return h(DefaultTheme.Layout, null, {
      'aside-outline-before': () => h(MyComponent)
    })
  }
}

Full list of slots available in the default theme layout:

• When layout: 'doc' (default) is enabled via frontmatter:
  • doc-top
  • doc-bottom
  • doc-footer-before
  • doc-before
  • doc-after
  • sidebar-nav-before
  • sidebar-nav-after
  • aside-top
  • aside-bottom
  • aside-outline-before
  • aside-outline-after
  • aside-ads-before
  • aside-ads-after
• When layout: 'home' is enabled via frontmatter:
  • home-hero-before
  • home-hero-info-before
  • home-hero-info
  • home-hero-info-after
  • home-hero-actions-before-actions
  • home-hero-actions-after
  • home-hero-image
  • home-hero-after
  • home-features-before
  • home-features-after
• When layout: 'page' is enabled via frontmatter:
  • page-top
  • page-bottom
• On not found (404) page:
  • not-found
• Always:
  • layout-top
  • layout-bottom
  • nav-bar-title-before
  • nav-bar-title-after
  • nav-bar-content-before
  • nav-bar-content-after
  • nav-screen-content-before
  • nav-screen-content-after

Using View Transitions API Copy Chapter

On Appearance Toggle Copy Section

You can extend the default theme to provide a custom transition when the color mode is toggled. An example:

<script setup lang="ts">
import { useData } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import { nextTick, provide } from 'vue'

const { isDark } = useData()

const enableTransitions = () =>
  'startViewTransition' in document &&
  window.matchMedia('(prefers-reduced-motion: no-preference)').matches

provide('toggle-appearance', async ({ clientX: x, clientY: y }: MouseEvent) => {
  if (!enableTransitions()) {
    isDark.value = !isDark.value
    return
  }

  const clipPath = [
    `circle(0px at ${x}px ${y}px)`,
    `circle(${Math.hypot(
      Math.max(x, innerWidth - x),
      Math.max(y, innerHeight - y)
    )}px at ${x}px ${y}px)`
  ]

  await document.startViewTransition(async () => {
    isDark.value = !isDark.value
    await nextTick()
  }).ready

  document.documentElement.animate(
    { clipPath: isDark.value ? clipPath.reverse() : clipPath },
    {
      duration: 300,
      easing: 'ease-in',
      fill: 'forwards',
      pseudoElement: `::view-transition-${isDark.value ? 'old' : 'new'}(root)`
    }
  )
})
</script>

<template>
  <DefaultTheme.Layout />
</template>

<style>
::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
}

::view-transition-old(root),
.dark::view-transition-new(root) {
  z-index: 1;
}

::view-transition-new(root),
.dark::view-transition-old(root) {
  z-index: 9999;
}

.VPSwitchAppearance {
  width: 22px !important;
}

.VPSwitchAppearance .check {
  transform: none !important;
}
</style>

Result (warning!: flashing colors, sudden movements, bright lights):

Demo

Refer Chrome Docs from more details on view transitions.

On Route Change Copy Section

Coming soon.

Overriding Internal Components Copy Chapter

You can use Vite's aliases to replace default theme components with your custom ones:

import { fileURLToPath, URL } from 'node:url'
import { defineConfig } from 'vitepress'

export default defineConfig({
  vite: {
    resolve: {
      alias: [
        {
          find: /^.*\/VPNavBar\.vue$/,
          replacement: fileURLToPath(
            new URL('./theme/components/CustomNavBar.vue', import.meta.url)
          )
        }
      ]
    }
  }
})

To know the exact name of the component refer our source code. Since the components are internal, there is a slight chance their name is updated between minor releases.

File: docs/en/guide/frontmatter.md Copy Chapter

Frontmatter

Usage Copy Chapter

VitePress supports YAML frontmatter in all Markdown files, parsing them with gray-matter. The frontmatter must be at the top of the Markdown file (before any elements including <script> tags), and must take the form of valid YAML set between triple-dashed lines. Example:

---
title: Docs with VitePress
editLink: true
---

Many site or default theme config options have corresponding options in frontmatter. You can use frontmatter to override specific behavior for the current page only. For details, see Frontmatter Config Reference.

You can also define custom frontmatter data of your own, to be used in dynamic Vue expressions on the page.

Accessing Frontmatter Data Copy Chapter

Frontmatter data can be accessed via the special $frontmatter global variable:

Here's an example of how you could use it in your Markdown file:

---
title: Docs with VitePress
editLink: true
---

# {{ $frontmatter.title }}

Guide content

You can also access current page's frontmatter data in <script setup> with the useData() helper.

Alternative Frontmatter Formats Copy Chapter

VitePress also supports JSON frontmatter syntax, starting and ending in curly braces:

---
{
  "title": "Blogging Like a Hacker",
  "editLink": true
}
---

File: docs/en/guide/getting-started.md Copy Chapter

Getting Started

Try It Online Copy Chapter

You can try VitePress directly in your browser on StackBlitz.

Installation Copy Chapter

Prerequisites Copy Section

• Node.js version 22 or higher.
• Terminal for accessing VitePress via its command line interface (CLI).
• Text Editor with Markdown syntax support.
  • VSCode is recommended, along with the official Vue extension.

VitePress can be used on its own, or be installed into an existing project. In both cases, you can install it with:

::: code-group

$ npm add -D vitepress@next

$ pnpm add -D vitepress@next

$ yarn add -D vitepress@next vue

$ bun add -D vitepress@next

$ deno add -D vitepress@next

:::

::: tip NOTE

VitePress is an ESM-only package. Don't use require() to import it, and make sure your nearest package.json contains "type": "module", or change the file extension of your relevant files like .vitepress/config.js to .mjs/.mts. Refer to Vite's troubleshooting guide for more details. Also, inside async CJS contexts, you can use await import('vitepress') instead.

:::

Setup Wizard Copy Section

VitePress ships with a command line setup wizard that will help you scaffold a basic project. After installation, start the wizard by running:

::: code-group

$ npx vitepress init

$ pnpm vitepress init

$ yarn vitepress init

$ bun vitepress init

:::

You will be greeted with a few simple questions:

<<< @/snippets/init.ansi

::: tip Vue as Peer Dependency
If you intend to perform customization that uses Vue components or APIs, you should also explicitly install vue as a dependency.
:::

File Structure Copy Chapter

If you are building a standalone VitePress site, you can scaffold the site in your current directory (./). However, if you are installing VitePress in an existing project alongside other source code, it is recommended to scaffold the site in a nested directory (e.g. ./docs) so that it is separate from the rest of the project.

Assuming you chose to scaffold the VitePress project in ./docs, the generated file structure should look like this:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

The docs directory is considered the project root of the VitePress site. The .vitepress directory is a reserved location for VitePress' config file, dev server cache, build output, and optional theme customization code.

::: tip
By default, VitePress stores its dev server cache in .vitepress/cache, and the production build output in .vitepress/dist. If using Git, you should add them to your .gitignore file. These locations can also be configured.
:::

The Config File Copy Section

The config file (.vitepress/config.js) allows you to customize various aspects of your VitePress site, with the most basic options being the title and description of the site:

export default {
  // site-level options
  title: 'VitePress',
  themeConfig: {
    // theme-level options
  }
}

You can also configure the behavior of the theme via the themeConfig option. Consult the Config Reference for full details on all config options.

Source Files Copy Section

Markdown files outside the .vitepress directory are considered source files.

VitePress uses file-based routing: each .md file is compiled into a corresponding .html file with the same path. For example, index.md will be compiled into index.html, and can be visited at the root path / of the resulting VitePress site.

VitePress also provides the ability to generate clean URLs, rewrite paths, and dynamically generate pages. These will be covered in the Routing Guide.

Up and Running Copy Chapter

The tool should have also injected the following npm scripts to your package.json if you allowed it to do so during the setup process:

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}

The docs:dev script will start a local dev server with instant hot updates. Run it with the following command:

::: code-group

$ npm run docs:dev

$ pnpm run docs:dev

$ yarn docs:dev

$ bun run docs:dev

:::

Instead of npm scripts, you can also invoke VitePress directly with:

::: code-group

$ npx vitepress dev docs

$ pnpm vitepress dev docs

$ yarn vitepress dev docs

$ bun vitepress dev docs

:::

More command line usage is documented in the CLI Reference.

The dev server should be running at http://localhost:5173. Visit the URL in your browser to see your new site in action!

What's Next? Copy Chapter

• To better understand how markdown files are mapped to generated HTML, proceed to the Routing Guide.

• To discover more about what you can do on the page, such as writing markdown content or using Vue Components, refer to the "Writing" section of the guide. A great place to start would be to learn about Markdown Extensions.

• To explore the features provided by the default documentation theme, check out the Default Theme Config Reference.

• If you want to further customize the appearance of your site, explore how to either Extend the Default Theme or Build a Custom Theme.

• Once your documentation site takes shape, make sure to read the Deployment Guide.

File: docs/en/guide/i18n.md Copy Chapter

Internationalization

To use the built-in i18n features, one needs to create a directory structure as follows:

docs/
├─ es/
│  ├─ foo.md
├─ fr/
│  ├─ foo.md
├─ foo.md

Then in docs/.vitepress/config.ts:

import { defineConfig } from 'vitepress'

export default defineConfig({
  // shared properties and other top-level stuff...

  locales: {
    root: {
      label: 'English',
      lang: 'en'
    },
    fr: {
      label: 'French',
      lang: 'fr', // optional, will be added  as `lang` attribute on `html` tag
      link: '/fr/guide' // default /fr/ -- shows on navbar translations menu, can be external

      // other locale specific properties...
    }
  }
})

The following properties can be overridden for each locale (including root):

interface LocaleSpecificConfig {
  lang?: string
  dir?: string
  title?: string
  titleTemplate?: string | boolean
  description?: string
  head?: HeadConfig[] // will be merged with existing head entries, duplicate meta tags are automatically removed
  themeConfig?: ThemeConfig // will be shallow merged, common stuff can be put in top-level themeConfig entry
}

Refer DefaultTheme.Config interface for details on customizing the placeholder texts of the default theme. Don't override themeConfig.algolia or themeConfig.carbonAds at locale-level. Refer Algolia docs for using multilingual search.

Pro tip: Config file can be stored at docs/.vitepress/config/index.ts too. It might help you organize stuff by creating a configuration file per locale and then merge and export them from index.ts.

Per-locale Markdown Strings Copy Chapter

Strings baked into pages by the markdown renderer - the default titles of custom containers and GitHub-flavored alerts, and the strings of the code copy button - can be overridden per locale with the markdown key of a locale entry:

import { defineConfig } from 'vitepress'

export default defineConfig({
  locales: {
    root: { label: 'English', lang: 'en' },
    zh: {
      label: '简体中文',
      lang: 'zh-Hans',
      markdown: {
        container: {
          tipLabel: '提示',
          warningLabel: '警告'
          // ...the other labels, and titles of `customContainers`
        },
        codeCopyButton: {
          tooltipText: '复制代码',
          copiedText: '已复制'
        }
      }
    }
  }
})

Values fall back to the root-level markdown options when a locale leaves them unset. Locale entries can only override the titles of containers registered at the root level - registering new containers per locale is not supported. Also note that since the markdown renderer is created once for the whole site, these can only be declared in the main config file, not in additional configs.

Separate directory for each locale Copy Chapter

The following is a perfectly fine structure:

docs/
├─ en/
│  ├─ foo.md
├─ es/
│  ├─ foo.md
├─ fr/
   ├─ foo.md

However, VitePress won't redirect / to /en/ by default. You'll need to configure your server for that. For example, on Netlify, you can add a docs/public/_redirects file like this:

/*  /es/:splat  302  Language=es
/*  /fr/:splat  302  Language=fr
/*  /en/:splat  302

Pro tip: If using the above approach, you can use nf_lang cookie to persist user's language choice:

import DefaultTheme from 'vitepress/theme'
import Layout from './Layout.vue'

export default {
  extends: DefaultTheme,
  Layout
}

<script setup lang="ts">
import DefaultTheme from 'vitepress/theme'
import { useData, inBrowser } from 'vitepress'
import { watchEffect } from 'vue'

const { lang } = useData()
watchEffect(() => {
  if (inBrowser) {
    document.cookie = `nf_lang=${lang.value}; expires=Mon, 1 Jan 2030 00:00:00 UTC; path=/`
  }
})
</script>

<template>
  <DefaultTheme.Layout />
</template>

RTL Support (Experimental) Copy Chapter

For RTL support, specify dir: 'rtl' in config and use some RTLCSS PostCSS plugin like https://github.com/MohammadYounes/rtlcss, https://github.com/vkalinichev/postcss-rtl or https://github.com/elchininet/postcss-rtlcss. You'll need to configure your PostCSS plugin to use :where([dir="ltr"]) and :where([dir="rtl"]) as prefixes to prevent CSS specificity issues.

2. Official Technical Reference & Guides (vuejs/docs) Copy Chapter

File: README.md Copy Chapter

vuejs.org

Contributing Copy Chapter

This site is built with VitePress and depends on @vue/theme. Site content is written in Markdown format located in src. For simple edits, you can directly edit the file on GitHub and generate a Pull Request.

For local development, pnpm is preferred as package manager:

pnpm i
pnpm run dev

This project requires Node.js to be v20 or higher. And it is recommended to enable corepack:

corepack enable

Working on the content Copy Chapter

• See VitePress docs on supported Markdown Extensions and the ability to use Vue syntax inside markdown.

• See the Writing Guide for our rules and recommendations on writing and maintaining documentation content.

Working on the theme Copy Chapter

If changes need to be made for the theme, check out the instructions for developing the theme alongside the docs.

File: src/guide/extras/animation.md Copy Chapter

Animation Techniques {#animation-techniques}

Vue provides the ](/guide/built-ins/transition) and [ components for handling enter / leave and list transitions. However, there are many other ways of using animations on the web, even in a Vue application. Here we will discuss a few additional techniques.

Class-based Animations {#class-based-animations} Copy Chapter

For elements that are not entering / leaving the DOM, we can trigger animations by dynamically adding a CSS class:

const disabled = ref(false)

function warnDisabled() {
  disabled.value = true
  setTimeout(() => {
    disabled.value = false
  }, 1500)
}

export default {
  data() {
    return {
      disabled: false
    }
  },
  methods: {
    warnDisabled() {
      this.disabled = true
      setTimeout(() => {
        this.disabled = false
      }, 1500)
    }
  }
}

Click me
  This feature is disabled!

.shake {
  animation: shake 0.82s cubic-bezier(0.36, 0.07, 0.19, 0.97) both;
  transform: translate3d(0, 0, 0);
}

@keyframes shake {
  10%,
  90% {
    transform: translate3d(-1px, 0, 0);
  }

  20%,
  80% {
    transform: translate3d(2px, 0, 0);
  }

  30%,
  50%,
  70% {
    transform: translate3d(-4px, 0, 0);
  }

  40%,
  60% {
    transform: translate3d(4px, 0, 0);
  }
}

const x = ref(0)

function onMousemove(e) {
  x.value = e.clientX
}

export default {
  data() {
    return {
      x: 0
    }
  },
  methods: {
    onMousemove(e) {
      this.x = e.clientX
    }
  }
}

Move your mouse across this div...
  x: {{ x }}

.movearea {
  transition: 0.3s background-color ease;
}

import { ref, reactive, watch } from 'vue'
import gsap from 'gsap'

const number = ref(0)
const tweened = reactive({
  number: 0
})

// Note: For inputs greater than Number.MAX_SAFE_INTEGER (9007199254740991),
// the result may be inaccurate due to limitations in JavaScript number precision.
watch(number, (n) => {
  gsap.to(tweened, { duration: 0.5, number: Number(n) || 0 })
})

Type a number: 
{{ tweened.number.toFixed(0) }}

import gsap from 'gsap'

export default {
  data() {
    return {
      number: 0,
      tweened: 0
    }
  },
  // Note: For inputs greater than Number.MAX_SAFE_INTEGER (9007199254740991),
  // the result may be inaccurate due to limitations in JavaScript number precision.
  watch: {
    number(n) {
      gsap.to(this, { duration: 0.5, tweened: Number(n) || 0 })
    }
  }
}

Type a number: 
{{ tweened.toFixed(0) }}

<script setup>
import { ref, onMounted } from 'vue'

// reactive state
const count = ref(0)

// functions that mutate state and trigger updates
function increment() {
  count.value++
}

// lifecycle hooks
onMounted(() => {
  console.log(`The initial count is ${count.value}.`)
})
</script>

<template>
  Count is: {{ count }}
</template>

let A0 = 1
let A1 = 2
let A2 = A0 + A1

console.log(A2) // 3

A0 = 2
console.log(A2) // Still 3

let A2

function update() {
  A2 = A0 + A1
}

whenDepsChange(update)

function reactive(obj) {
  return new Proxy(obj, {
    get(target, key) {
      track(target, key)
      return target[key]
    },
    set(target, key, value) {
      target[key] = value
      trigger(target, key)
    }
  })
}

function ref(value) {
  const refObject = {
    get value() {
      track(refObject, 'value')
      return value
    },
    set value(newValue) {
      value = newValue
      trigger(refObject, 'value')
    }
  }
  return refObject
}

// This will be set right before an effect is about
// to be run. We'll deal with this later.
let activeEffect

function track(target, key) {
  if (activeEffect) {
    const effects = getSubscribersForProperty(target, key)
    effects.add(activeEffect)
  }
}

function trigger(target, key) {
  const effects = getSubscribersForProperty(target, key)
  effects.forEach((effect) => effect())
}

function whenDepsChange(update) {
  const effect = () => {
    activeEffect = effect
    update()
    activeEffect = null
  }
  effect()
}

import { ref, watchEffect } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = ref()

watchEffect(() => {
  // tracks A0 and A1
  A2.value = A0.value + A1.value
})

// triggers the effect
A0.value = 2

import { ref, computed } from 'vue'

const A0 = ref(0)
const A1 = ref(1)
const A2 = computed(() => A0.value + A1.value)

A0.value = 2

import { ref, watchEffect } from 'vue'

const count = ref(0)

watchEffect(() => {
  document.body.innerHTML = `Count is: ${count.value}`
})

// updates the DOM
count.value++

<script setup>
import { onRenderTracked, onRenderTriggered } from 'vue'

onRenderTracked((event) => {
  debugger
})

onRenderTriggered((event) => {
  debugger
})
</script>

export default {
  renderTracked(event) {
    debugger
  },
  renderTriggered(event) {
    debugger
  }
}

type DebuggerEvent = {
  effect: ReactiveEffect
  target: object
  type:
    | TrackOpTypes /* 'get' | 'has' | 'iterate' */
    | TriggerOpTypes /* 'set' | 'add' | 'delete' | 'clear' */
  key: any
  newValue?: any
  oldValue?: any
  oldTarget?: Map<any, any> | Set<any>
}

const plusOne = computed(() => count.value + 1, {
  onTrack(e) {
    // triggered when count.value is tracked as a dependency
    debugger
  },
  onTrigger(e) {
    // triggered when count.value is mutated
    debugger
  }
})

// access plusOne, should trigger onTrack
console.log(plusOne.value)

// mutate count.value, should trigger onTrigger
count.value++

watch(source, callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})

watchEffect(callback, {
  onTrack(e) {
    debugger
  },
  onTrigger(e) {
    debugger
  }
})

export default {
  watch: {
    source: {
      handler() {
        // ...
      },
      onTrack(e) {
        debugger
      },
      onTrigger(e) {
        debugger
      }
    }
  }
}

import { produce } from 'immer'
import { shallowRef } from 'vue'

export function useImmer(baseState) {
  const state = shallowRef(baseState)
  const update = (updater) => {
    state.value = produce(state.value, updater)
  }

  return [state, update]
}

import { createMachine, interpret } from 'xstate'
import { shallowRef } from 'vue'

export function useMachine(options) {
  const machine = createMachine(options)
  const state = shallowRef(machine.initialState)
  const service = interpret(machine)
    .onTransition((newState) => (state.value = newState))
    .start()
  const send = (event) => service.send(event)

  return [state, send]
}

const [count, setCount] = createSignal(0)

count() // access the value
setCount(1) // update the value

import { shallowRef, triggerRef } from 'vue'

export function createSignal(value, options) {
  const r = shallowRef(value)
  const get = () => r.value
  const set = (v) => {
    r.value = typeof v === 'function' ? v(r.value) : v
    if (options?.equals === false) triggerRef(r)
  }
  return [get, set]
}

const count = signal(0)

count() // access the value
count.set(1) // set new value
count.update((v) => v + 1) // update based on previous value

import { shallowRef } from 'vue'

export function signal(initialValue) {
  const r = shallowRef(initialValue)
  const s = () => r.value
  s.set = (value) => {
    r.value = value
  }
  s.update = (updater) => {
    r.value = updater(r.value)
  }
  return s
}

<script setup>
let count = $ref(0)

console.log(count)

function increment() {
  count++
}
</script>

<template>
  {{ count }}
</template>

import { ref } from 'vue'

let count = ref(0)

console.log(count.value)

function increment() {
  count.value++
}

import { $ref } from 'vue/macros'

let count = $ref(0)

import { useMouse } from '@vueuse/core'

const { x, y } = $(useMouse())

console.log(x, y)

import { toRef } from 'vue'
import { useMouse } from '@vueuse/core'

const __temp = useMouse(),
  x = toRef(__temp, 'x'),
  y = toRef(__temp, 'y')

console.log(x.value, y.value)

function myCreateRef() {
  return ref(0)
}

let count = $(myCreateRef())

<script setup lang="ts">
  interface Props {
    msg: string
    count?: number
    foo?: string
  }

  const {
    msg,
    // default value just works
    count = 1,
    // local aliasing also just works
    // here we are aliasing `props.foo` to `bar`
    foo: bar
  } = defineProps()

  watchEffect(() => {
    // will log whenever the props change
    console.log(msg, count, bar)
  })
</script>

export default {
  props: {
    msg: { type: String, required: true },
    count: { type: Number, default: 1 },
    foo: String
  },
  setup(props) {
    watchEffect(() => {
      console.log(props.msg, props.count, props.foo)
    })
  }
}

function trackChange(x: Ref<number>) {
  watch(x, (x) => {
    console.log('x changed!')
  })
}

let count = $ref(0)
trackChange(count) // doesn't work!

let count = ref(0)
trackChange(count.value)

let count = $ref(0)
- trackChange(count)
+ trackChange($$(count))

import { ref } from 'vue'

let count = ref(0)
trackChange(count)

function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // listen to mousemove...

  // doesn't work!
  return {
    x,
    y
  }
}

return {
  x: x.value,
  y: y.value
}

function useMouse() {
  let x = $ref(0)
  let y = $ref(0)

  // listen to mousemove...

  // fixed
  return $$({
    x,
    y
  })
}

const { count } = defineProps<{ count: number }>()

passAsRef($$(count))

setup(props) {
  const __props_count = toRef(props, 'count')
  passAsRef(__props_count)
}

/// <reference types="vue/macros-global" />

export default {
  plugins: [
    vue({
      reactivityTransform: true
    })
  ]
}

module.exports = {
  chainWebpack: (config) => {
    config.module
      .rule('vue')
      .use('vue-loader')
      .tap((options) => {
        return {
          ...options,
          reactivityTransform: true
        }
      })
  }
}

module.exports = {
  module: {
    rules: [
      {
        test: /\.vue$/,
        loader: 'vue-loader',
        options: {
          reactivityTransform: true
        }
      }
    ]
  }
}

import { h } from 'vue'

const vnode = h(
  'div', // type
  { id: 'foo', class: 'bar' }, // props
  [
    /* children */
  ]
)

// all arguments except the type are optional
h('div')
h('div', { id: 'foo' })

// both attributes and properties can be used in props
// Vue automatically picks the right way to assign it
h('div', { class: 'bar', innerHTML: 'hello' })

// props modifiers such as `.prop` and `.attr` can be added
// with `.` and `^` prefixes respectively
h('div', { '.name': 'some-name', '^width': '100' })

// class and style have the same object / array
// value support that they have in templates
h('div', { class: [foo, { bar }], style: { color: 'red' } })

// event listeners should be passed as onXxx
h('div', { onClick: () => {} })

// children can be a string
h('div', { id: 'foo' }, 'hello')

// props can be omitted when there are no props
h('div', 'hello')
h('div', [h('span', 'hello')])

// children array can contain mixed vnodes and strings
h('div', ['hello', h('span', 'hello')])

const vnode = h('div', { id: 'foo' }, [])

vnode.type // 'div'
vnode.props // { id: 'foo' }
vnode.children // []
vnode.key // null

import { ref, h } from 'vue'

export default {
  props: {
    /* ... */
  },
  setup(props) {
    const count = ref(1)

    // return the render function
    return () => h('div', props.msg + count.value)
  }
}

export default {
  setup() {
    return () => 'hello world!'
  }
}

import { h } from 'vue'

export default {
  setup() {
    // use an array to return multiple root nodes
    return () => [
      h('div'),
      h('div'),
      h('div')
    ]
  }
}

import { h } from 'vue'

export default {
  data() {
    return {
      msg: 'hello'
    }
  },
  render() {
    return h('div', this.msg)
  }
}

export default {
  render() {
    return 'hello world!'
  }
}

import { h } from 'vue'

export default {
  render() {
    // use an array to return multiple root nodes
    return [
      h('div'),
      h('div'),
      h('div')
    ]
  }
}

function Hello() {
  return 'hello world!'
}

function render() {
  const p = h('p', 'hi')
  return h('div', [
    // Yikes - duplicate vnodes!
    p,
    p
  ])
}

function render() {
  return h(
    'div',
    Array.from({ length: 20 }).map(() => {
      return h('p', 'hi')
    })
  )
}