In VitePress 1.6, how do you render a live Vue component demo inside a Markdown page, and which Markdown-specific rules can break it?

## A Markdown page is a Vue component VitePress compiles each `.md` file to HTML with markdown-it and then hands the result to Vue as a single-file component. The differences from an ordinary `.vue` file: - There is **no `<template>` tag**. All root-level content that is not `<script>` or `<style>` is Markdown, and it becomes the template. - Root-level `<script setup>`, `<script>` and `<style>` blocks work as in an SFC, but they must come **after the frontmatter**. - Vue syntax works in the text: `{{ }}` interpolation, directives such as `v-for` on raw HTML, and component tags. ## Showing a live demo For a component library's docs, each component page renders small demo components that live beside the docs: ```md --- title: Button --- <script setup> import ButtonBasic from './demos/ButtonBasic.vue' </script> # Button <ButtonBasic /> ``` There are two ways to make a component available: | Approach | How | When | |---|---|---| | import per page | `<script setup>` import in the `.md` file | demos used on one or a few pages; code-split per page | | register globally | `app.component('ButtonBasic', ButtonBasic)` in the theme's `enhanceApp` | components used on most pages | The page also has access to VitePress runtime helpers. `useData()` from `vitepress` returns refs such as `page`, `frontmatter`, `site`, `theme` and `isDark`, and templates can use `$frontmatter` directly: `{{ $frontmatter.title }}`. ## Rules that break demos 1. **Component names must be PascalCase or hyphenated.** `<ButtonBasic />` or `<button-basic />` is treated as a component. A lowercase name without a hyphen, like `<buttonbasic />`, is treated as an inline HTML element, so Markdown wraps it in a `<p>`. Block content inside `<p>` is invalid, and the server HTML and the client render disagree: a **hydration mismatch**. 2. **Code fences are not interpolated.** VitePress wraps every fenced code block in `v-pre`, so `{{ count }}` inside a fence shows literally. That is what you want for code samples. To interpolate inside a fence, add `-vue` to the language, such as `js-vue`, at some cost to highlighting. 3. **Escaping in text needs `v-pre`.** To show `{{ }}` in prose, wrap it in an element with `v-pre`, or use a `::: v-pre` container. 4. **Prefer `<style module>` to `<style scoped>`.** Scoped styles in Markdown add a data attribute to every element on the page, bloating it; CSS modules keep styles local without that cost. 5. **Mind components in headings.** `# Button <Badge text="beta" />` renders the component but leaves it out of the parsed title used by the sidebar and outline; wrapping it in backticks shows it as code instead. 6. **Everything must render in Node.** The build prerenders the page, so a demo that touches `window` during setup breaks the build even though `vitepress dev` never noticed. ## Why this model is cheap Because pages are compiled by Vue, static Markdown is separated from dynamic parts. For the first visit, static content is left out of the page's JavaScript and skipped during hydration, so a long guide with one live demo pays only for the demo. ## Organising demos for a whole library One page per component quickly means dozens of demo files. A structure that scales: - Keep demos as small `.vue` files beside the docs, such as `docs/components/demos/ButtonBasic.vue`, each showing one use case. - Import the library in demos the way users will, from its package entry or an alias that points at the source, so the docs exercise the public API. - Give every demo a PascalCase name that states the case: `ButtonLoading`, `ButtonIconOnly`. - Wrap demos in one shared, globally registered `DemoBlock` component that adds a frame, a title and a toggle to show the source. The page then reads like prose with components dropped in, and the source shown next to each demo can be imported from the same file with VitePress's snippet syntax, so the rendered demo and the displayed code never disagree. ## Reading page data in a demo A demo or wrapper can adapt to the page it sits on. `useData()` gives reactive access to the page's `frontmatter`, so a page can set `demoTheme: compact` in its frontmatter and the wrapper reads it. `isDark` reports the current colour mode, which is useful when a demo must restyle itself for dark mode. ## Checklist for a demo page - Script after frontmatter, imports relative to the page. - PascalCase component tags. - Code samples in fences, not in raw HTML. - Styles in `<style module>` or in the demo component. - Demo code safe to render during the build.