VitePress Custom Vue Components Development

Developing Custom Vue Components for VitePress

VitePress allows using Vue 3 SFC components directly in Markdown via global registration or import. This is the key advantage over Docusaurus for Vue-oriented projects.

Registration and Usage

// .vitepress/theme/index.ts
import { defineAsyncComponent } from 'vue';
import DefaultTheme from 'vitepress/theme';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // Synchronous registration
    app.component('CodePlayground', CodePlayground);

    // Asynchronous (lazy loading)
    app.component('HeavyChart', defineAsyncComponent(() =>
      import('./components/HeavyChart.vue')
    ));
  },
};

# How it works

<CodePlayground
  :code="`const x = 1 + 1;\nconsole.log(x);`"
  language="javascript"
/>

Interactive Code Playground

<!-- .vitepress/theme/components/CodePlayground.vue -->
<script setup lang="ts">
import { ref, computed, onMounted } from 'vue';
import { shikiToHighlighter } from '@shikijs/vitepress-twoslash';

const props = defineProps<{
  code: string;
  language: string;
  editable?: boolean;
}>();

const userCode = ref(props.code);
const output = ref('');
const isRunning = ref(false);

const highlighted = computed(() => {
  // Use Shiki for highlighting
  return highlighter.codeToHtml(userCode.value, { lang: props.language });
});

const runCode = async () => {
  isRunning.value = true;
  const logs: string[] = [];
  const sandbox = new Function('console', userCode.value);
  try {
    sandbox({ log: (...args) => logs.push(args.join(' ')) });
    output.value = logs.join('\n');
  } catch (e: any) {
    output.value = `Error: ${e.message}`;
  }
  isRunning.value = false;
};
</script>

<template>
  <div class="code-playground">
    <div class="code-playground__editor">
      <textarea
        v-if="editable"
        v-model="userCode"
        class="code-playground__textarea"
        spellcheck="false"
      />
      <div v-else v-html="highlighted" />
    </div>
    <div class="code-playground__footer">
      <button @click="runCode" :disabled="isRunning">
        {{ isRunning ? 'Running...' : '▶ Run' }}
      </button>
      <pre v-if="output" class="code-playground__output">{{ output }}</pre>
    </div>
  </div>
</template>

UI Demo Component

<!-- UI Component Demo -->
<script setup lang="ts">
import { ref } from 'vue';

const variant = ref('primary');
const disabled = ref(false);
</script>

<template>
  <div class="component-demo">
    <div class="demo-preview">
      <button :class="`btn btn--${variant}`" :disabled="disabled">
        Sample Button
      </button>
    </div>

    <div class="demo-controls">
      <label>
        Variant:
        <select v-model="variant">
          <option value="primary">Primary</option>
          <option value="secondary">Secondary</option>
          <option value="danger">Danger</option>
        </select>
      </label>
      <label>
        <input type="checkbox" v-model="disabled"> Disabled
      </label>
    </div>
  </div>
</template>

Component with API Data

<script setup lang="ts">
import { ref, onMounted } from 'vue';
// VitePress supports only browser-compatible code in components
// Data should be passed via props from Markdown frontmatter
// or loaded on client

const props = defineProps<{ endpoint: string }>();
const data = ref(null);

onMounted(async () => {
  // Requests only in browser (not during SSG)
  if (typeof window !== 'undefined') {
    data.value = await fetch(props.endpoint).then(r => r.json());
  }
});
</script>

Global Data via useData

<script setup>
import { useData, useRoute } from 'vitepress';
const { site, page, theme, frontmatter, lang, isDark } = useData();
const route = useRoute();
</script>

<template>
  <div>{{ frontmatter.title }} | {{ site.title }}</div>
  <div>Current path: {{ route.path }}</div>
</template>

Developing 3–5 custom Vue components for documentation — 2–4 days.