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,StepsandTypeTable. - Search in the browser, from an index generated at build time, so it works on a static host.
/robots.txt,/llms.txtand/llms-full.txt, and/sitemap.xmlonce 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 andmeta.jsonfiles, 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
layoutsof the theme, where Fumapress hasui.renderPagein 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
layouttorenderDefault(). - A page is a
.mdfile written with Vue's template syntax, where Fumadocs has MDX:{{ value }}in place of{value},:prop="value"in place ofprop={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 hasmdxOptionsandsatteriOptions. - A page with
draft: trueis a draft:vuesho devshows it, and a build leaves it out. - The folder of
defineDocs()iscontentby default, where Fumadocs MDX hascontent/docs, so a site with or withoutvuesho.config.tsreads the same folder. defineCollections()defines pages only, withtype: "doc". Themeta.jsonfiles of a folder are in the collection ofdefineDocs().- A custom page is a component, with props the server gives in
definePage(), where a custom page of Fumapress is a React Server Component.