Using Vue in Markdown

In VitePress, each Markdown file is compiled into HTML and then processed as a Vue Single-File Component. This means you can use any Vue features inside the Markdown, including dynamic templating, using Vue components, or arbitrary in-page Vue component logic by adding a <script> tag.

It's worth noting that VitePress leverages Vue's compiler to automatically detect and optimize the purely static parts of the Markdown content. Static contents are optimized into single placeholder nodes and eliminated from the page's JavaScript payload for initial visits. They are also skipped during client-side hydration. In short, you only pay for the dynamic parts on any given page.

Each Markdown file is first compiled into HTML and then passed on as a Vue component to the Vite process pipeline. This means you can use Vue-style interpolation in text:

Input

{{ 1 + 1 }}

Output

{{ 1 + 1 }}

Directives also work (note that by design, raw HTML is also valid in Markdown):

Input

<span v-for="i in 3">{{ i }}</span>

Output

{{ i }}

Root-level <script> and <style> tags in Markdown files work just like they do in Vue SFCs, including <script setup>, <style module>, etc. The main difference here is that there is no <template> tag: all other root-level content is Markdown. Also note that all tags should be placed after the frontmatter:

---
hello: world
---

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

const count = ref(0)
</script>

## Markdown Content

The count is: {{ count }}

<button :class="$style.button" @click="count++">Increment</button>

<style module>
.button {
  color: red;
  font-weight: bold;
}
</style>

You also have access to VitePress' runtime APIs such as the useData helper, which provides access to current page's metadata:

Input

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

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

<pre>{{ page }}</pre>

Output

{
  "path": "/using-vue.html",
  "title": "Using Vue in Markdown",
  "frontmatter": {},
  ...
}

You can import and use Vue components directly in Markdown files.

If a component is only used by a few pages, it's recommended to explicitly import them where they are used. This allows them to be properly code-split and only loaded when the relevant pages are shown:

<script setup>
import CustomComponent from '../components/CustomComponent.vue'
</script>

# Docs

This is a .md using a custom component

<CustomComponent />

## More docs

...

If a component is going to be used on most of the pages, they can be registered globally by customizing the Vue app instance. See relevant section in Extending Default Theme for an example.

You can use Vue components in the headers, but note the difference between the following syntaxes:

The HTML wrapped by <code> will be displayed as-is; only the HTML that is not wrapped will be parsed by Vue.

You can escape Vue interpolations by wrapping them in a <span> or other elements with the v-pre directive:

Input

This <span v-pre>{{ will be displayed as-is }}</span>

Output

This {}

Alternatively, you can wrap the entire paragraph in a v-pre custom container:

::: v-pre
{{ This will be displayed as-is }}
:::

Output

{}

By default, all fenced code blocks are automatically wrapped with v-pre, so no Vue syntax will be processed inside. To enable Vue-style interpolation inside fences, you can append the language with the -vue suffix, e.g. js-vue:

Input

```js-vue
Hello {{ 1 + 1 }}
```

Output

Hello {{ 1 + 1 }}

Note that this might prevent certain tokens from being syntax highlighted properly.

VitePress has built-in support for CSS pre-processors: .scss, .sass, .less, .styl and .stylus files. There is no need to install Vite-specific plugins for them, but the corresponding pre-processor itself must be installed:

# .scss and .sass
npm install -D sass

# .less
npm install -D less

# .styl and .stylus
npm install -D stylus

Then you can use the following in Markdown and theme components:

<style lang="sass">
.title
  font-size: 20px
</style>

VitePress currently has SSG support for teleports to body only. For other targets, you can wrap them inside the built-in <ClientOnly> component or inject the teleport markup into the correct location in your final page HTML through postRender hook.

<script setup lang="ts">
import { ref } from 'vue'
const showModal = ref(false)
</script>

<template>
  <button class="modal-button" @click="showModal = true">Show Modal</button>

  <Teleport to="body">
    <Transition name="modal">
      <div v-show="showModal" class="modal-mask">
        <div class="modal-container">
          <p>Hello from the modal!</p>
          <div class="model-footer">
            <button class="modal-button" @click="showModal = false">
              Close
            </button>
          </div>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

<style scoped>
.modal-mask {
  position: fixed;
  z-index: 200;
  inset: 0;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  transition: opacity 0.3s ease;
}

.modal-container {
  width: 18.75rem;
  margin: auto;
  padding: 1.25rem 1.875rem;
  background-color: var(--vp-c-bg);
  border-radius: 0.125rem;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.33);
  transition: all 0.3s ease;
}

.model-footer {
  margin-top: 0.5rem;
  text-align: right;
}

.modal-button {
  padding: 0.25rem 0.5rem;
  border-radius: 0.25rem;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}

.modal-button:hover {
  border-color: var(--vp-button-alt-hover-border);
  color: var(--vp-button-alt-hover-text);
  background-color: var(--vp-button-alt-hover-bg);
}

.modal-enter-from,
.modal-leave-to {
  opacity: 0;
}

.modal-enter-from .modal-container,
.modal-leave-to .modal-container {
  transform: scale(1.1);
}
</style>

<ClientOnly>
  <Teleport to="#modal">
    <div>
      // ...
    </div>
  </Teleport>
</ClientOnly>

Vue provides IntelliSense support out of the box via the Vue - Official VS Code plugin. However, to enable it for .md files, you need to make some adjustments to the configuration files.

1. Add .md pattern to the include and vueCompilerOptions.vitePressExtensions options in the tsconfig/jsconfig file:

{
  "include": [
    "docs/**/*.ts",
    "docs/**/*.vue",
    "docs/**/*.md",
  ],
  "vueCompilerOptions": {
    "vitePressExtensions": [".md"],
  },
}

2. Add markdown to the vue.server.includeLanguages option in the VS Code setting:

{
  "vue.server.includeLanguages": ["vue", "markdown"]
}