Markdown
The syntax and components of a page.
A page is a Markdown file, .md, written with the template syntax of Vue: components with Markdown inside them, directives like :prop and @click, {{ value }}, and <script setup>. Everything of CommonMark and GFM works, like tables, task lists, strikethrough, footnotes and links from bare URLs, and emoji shortcodes like :tada:.
Frontmatter
---
title: Getting Started
description: Install and run the app.
icon: Rocket
full: true
---title: the main heading of the page, its name in the sidebar, and its<title>.description: the text below the title, and the meta description of the page.icon: the icon of the page in the sidebar.full: the page uses the full width, without the table of contents.draft: the page is a draft, which a build leaves out.date: when the page was written, like2026-01-31. It is aDateinpage.data, and plugins read it withgetPageCreatedAt(). A value that isn't a date fails the build.layout: the layout of the theme that renders the page, in place of the one of its source, see Layout of a Page.
title is required. Since it is the main heading, start the body at ##. Other fields need a schema, which adds them to page.data, where plugins and layouts read them.
Headings
Headings are listed in the table of contents. Each heading gets an id from its text, and [#id] at the end sets your own:
## Installation [#install]The heading links to #install. A heading that ends with [!toc] isn't in the table of contents, and one that ends with [toc] is only in the table of contents.
Code Blocks
Code blocks are highlighted at build time and have a copy button. Add a title after the language:
```ts title="hello.ts"
export function hello(name: string) {
return `Hello, ${name}!`;
}
```lineNumbers shows line numbers, and noCopy removes the copy button. Vue doesn't read the content of a code block or of inline code, so {{ }} stays as it is written.
Highlighting Lines
Mark a line with a comment in the code. The comment is removed from the output:
```ts
const a = 1;
const b = 2;
const c = 3;
```[!code highlight] highlights the line, and [!code ++] and [!code --] mark it as added or removed.
Code Themes
Code blocks are colored with the code themes GitHub Light in light mode and GitHub Dark in dark mode. To use other code themes, install @pierre/highlights and pass two of its themes to markdown.highlight of the Vite plugin:
import ayuLight from "@pierre/highlights/themes/ayu-light";
import dracula from "@pierre/highlights/themes/dracula";
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";
export default defineConfig({
plugins: [vuesho({ markdown: { highlight: { themes: { light: ayuLight, dark: dracula } } } })],
});The light code theme colors code blocks in light mode, and the dark code theme in dark mode. The languages are built into the highlighter, and a language it doesn't know is shown as plain text.
Code Tabs
Consecutive code blocks with a tab are grouped into tabs:
```ts tab="TypeScript"
const value: number = 1;
```
```js tab="JavaScript"
const value = 1;
```Package Managers
A code block with the language npm becomes tabs with the command for npm, pnpm, Yarn and Bun:
```npm
npm i vuesho
```Images

A relative path is a file next to the page, which the build includes. A path starting with / is a file of public, and gets the base path. The src of an element or a component, like ImageZoom, follows the same rules.
Components
Components are written as in a Vue template, and their content is Markdown. The content can be indented, and needs no blank lines around it:
<Callout type="warn" title="Careful">
This can't be **undone**.
</Callout>A prop takes a string, or a value with : in front, and a named slot is a <template>:
<Card :title="'Deploy'" href="/deploy">
<template #icon>🚀</template>
Put the site online.
</Card>The components of Fumadocs UI are available by name, without an import. See Components for the full list, and Your Own Components to add yours.
Callouts
A box for a note or a warning. type is info, warn, error, success or idea, and title is optional:
<Callout type="warn" title="Careful">
This can't be undone.
</Callout>Cards
Cards link to other pages:
<Cards>
<Card title="Quick Start" href="/quick-start">
Create a site from an empty folder.
</Card>
<Card title="Markdown" href="/markdown" />
</Cards>Steps
Numbered steps, each with a heading and its content:
<Steps>
<Step>
### Install the Package
Run the install command.
</Step>
<Step>
### Add the Plugin
Add it to `vite.config.ts`.
</Step>
</Steps>Tabs
<Tabs :items="['Vue', 'React']">
<Tab value="Vue">Content for Vue.</Tab>
<Tab value="React">Content for React.</Tab>
</Tabs>items are the labels, and the value of each Tab matches one of them. defaultIndex sets the tab open first.
Accordions
<Accordions>
<Accordion title="Is a server required?">
No, a site with only Markdown content is static.
</Accordion>
<Accordion title="Can I use Vue components?">Yes, in any page.</Accordion>
</Accordions>One accordion is open at a time. Add multiple to Accordions to open several.
Files
A file tree, with folders that open on click:
<Files>
<Folder name="content" default-open>
<File name="index.md" />
<File name="meta.json" />
</Folder>
<File name="vite.config.ts" />
</Files>Type Table
The props of a component or the options of a function:
<TypeTable
:type="{
dir: {
type: 'string',
description: 'The folder of the collection.',
required: true,
},
pagesDir: {
type: 'string',
description: 'The folder of custom pages.',
default: '"src/pages"',
},
}"
/>Image Zoom
An image that opens full size on click:
<ImageZoom src="/screenshot.png" alt="The editor" />Other Components
CodeBlockTabs and the parts of Tabs (TabsList, TabsTrigger, TabsContent) build tabs of your own layout, and ClientOnly renders its content only in the browser.
Vue in a Page
A page is a Vue component: {{ }} renders a value, a directive like v-if, v-for or @click works on any element, and <script setup> holds the code of the page. Import a Vue component there and use it like a tag:
Clicked {{ count }} times.
<Counter />
<script setup>
import { ref } from "vue";
import Counter from "../src/components/Counter.vue";
const count = ref(0);
</script>The page renders on the server and hydrates in the browser, so it follows the rules of Vue SSR: use browser APIs in onMounted or event handlers. <script setup lang="ts"> writes the code in TypeScript, <style>, <style scoped> and <style module> (as $style) style the page, in any lang Vite compiles, and usePage() of vuesho/client reads the page, like its frontmatter in page.data.
Outside {{ }}, braces are text, so {a, b} in a sentence stays as it is. A < that starts no tag is text too, like in a < b. For a tag written as text, like Array<string>, use inline code or \<.
Your Own Components
The components a page uses by name come from a components module, vuesho/components by default. To add yours, create src/components.ts and export them by name, with the components of the package:
export * from "vuesho/components";
export { default as Badge } from "./components/Badge.vue";This is <Badge text="new" />.A page imports only the components it uses, so a component that one page uses is loaded by that page only. A name that is the name of an element, like a, img, pre, table or h2, replaces the element that Markdown renders, so every link, image or code block of Markdown renders with your component. To use another file than src/components.ts, set the components option of the Vite plugin.
A component that src/components.ts doesn't export fails the build, at its line in the page:
content/index.md:3:9: `<Badge>` is not a component of /src/components.ts or an import of the page: check its name, export it from the components module, or import it in `<script setup>`. (E-UNKNOWN-COMPONENT)Partials
A Markdown file whose name starts with _ isn't a page, so it can hold content that several pages share. Import it in the <script setup> of a page and use it like a component:
<Callout>
Node.js 24 or later is required.
</Callout>
```npm
npm i vuesho
```## Installation
<Install />
<script setup>
import Install from "../_install.md";
</script>A partial uses the same components as a page. Its headings and text aren't in the table of contents or the search index of the page that imports it.
<include> embeds a file in place, so its headings and text are part of the page. A path ending with #id embeds the section under the heading with that id, and a file that isn't Markdown is a code block:
<include>../_install.md</include>
<include>./api.md#options</include>
<include>../src/config.ts</include>Coming From MDX or VitePress
A page of Fumadocs, Docusaurus or VitePress needs a few changes. A page reads the syntax of those tools as Markdown and text, so {value} or :::note renders as it is written. Write these instead:
| Syntax | In a page of Vuesho |
|---|---|
{value} | {{ value }} |
prop={value} | :prop="value" |
{...props} | v-bind="props" |
icon={<Rocket />} | <template #icon><Rocket /></template> |
{/* note */} | <!-- note --> |
import and export lines | <script setup> |
{items.map((item) => <li>…</li>)} | <li v-for="item in items">{{ item }}</li> |
:::warning[Careful] and > [!WARNING] | <Callout type="warn" title="Careful"> |
::: code-group | code blocks with tab="…" |
## Title {#id} | ## Title [#id] |
### Install [step] | <Steps> and <Step> |
props and $frontmatter | usePage() of vuesho/client |
A collection lists the .md files of its folder, so rename an .mdx page to .md.
Compile Options
The markdown option of the Vite plugin sets how the Markdown files of the site compile. A collection with its own markdown compiles its pages with those options instead.
markdownItPlugins: plugins of markdown-it, the parser of pages, which add syntax. What a plugin adds renders as the HTML of its renderer.highlight: the code themes of code blocks.footnoteLabel: the heading of the footnotes, read by screen readers,Footnotesby default.
With @mdit/plugin-katex and katex installed, $x^2$ and $$ blocks are math:
import { katex } from "@mdit/plugin-katex";
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";
export default defineConfig({
plugins: [vuesho({ markdown: { markdownItPlugins: [katex] } })],
});Import the stylesheet of KaTeX, katex/dist/katex.css, in your theme module.