Skip to Content
Vuesho

Introduction

A docs framework for Vue, on Vite and Nitro.

Vuesho turns the Markdown files of a folder into a docs site. It is a Vite plugin: Nitro prerenders the pages and serves the rest, and the app navigates between pages without loading a new document.

What a Site Gets

Write pages under content/ and run vuesho dev. Without any configuration, the site has:

  • A docs layout with a sidebar built from your files, a table of contents, and light and dark color modes.
  • Markdown with Vue's template syntax, highlighted code blocks, and components like Callout, Tabs, Steps and TypeTable.
  • Search in the browser, from an index generated at build time, so it works on a static host.
  • /robots.txt, /llms.txt and /llms-full.txt, and /sitemap.xml once you set the URL of the site.
  • Pages prerendered to HTML at build time, with client-side navigation after the first load.

Files of a Site

Only the pages are required. The other files are optional, and each runs in its own place:

  • vite.config.ts: the Vite config with the Vuesho plugin, for the compile options of Markdown and the options of Nitro. It runs in Vite, on the dev server and in the build.
  • content/: the pages and meta.json files, compiled by Vite.
  • vuesho.config.ts: the content, site options and plugins. It runs on the server, so it can read secrets. The build runs only its collection macros and what their options use.
  • src/theme.ts: the theme, which gives content pages their layouts and adds icons. It runs on the server and in the browser.
  • src/components.ts: the components of content, which pages use by name. It runs on the server and in the browser.
  • src/theme.css: the stylesheet, in place of the default one.
  • src/pages/: custom pages, Vue files that render on the server and in the browser, with props from the server.

Differences from Fumapress and Fumadocs

Vuesho is Fumapress for Vue. Its config has the shape of the config of Fumapress, which runs on React: createSite() is the createPress() chain of Fumapress, and plugin hooks have the same names and signatures. The UI is a port of Fumadocs UI to Vue, with the same markup and Tailwind CSS classes. The package bundles the parts of Fumadocs it uses, so a site installs neither Fumadocs nor React.

The differences:

  • The UI of the pages of a source is a component in layouts of the theme, where Fumapress has ui.renderPage in the config: the config runs on the server only, and a component runs in the browser too.
  • A view of a plugin returns props, and a theme names the component that renders them, since the server can't send a component to the browser.
  • A theme builds on the default theme or the base theme only when it names it in extends.
  • The layout is a component the theme imports, where Fumapress passes layout to renderDefault().
  • A page is a .md file written with Vue's template syntax, where Fumadocs has MDX: {{ value }} in place of {value}, :prop="value" in place of prop={value}, and imports in <script setup>.
  • The compile options of a collection are markdown, with the same shape as the option of the Vite plugin, where Fumadocs MDX has mdxOptions and satteriOptions.
  • A page with draft: true is a draft: vuesho dev shows it, and a build leaves it out.
  • The folder of defineDocs() is content by default, where Fumadocs MDX has content/docs, so a site with or without vuesho.config.ts reads the same folder.
  • defineCollections() defines pages only, with type: "doc". The meta.json files of a folder are in the collection of defineDocs().
  • A custom page is a component, with props the server gives in definePage(), where a custom page of Fumapress is a React Server Component.

Next Steps