UI
The layouts and components of your site, from Fumadocs UI ported to Vue.
The UI of Vuesho is Fumadocs UI ported to Vue, with Reka UI in place of Base UI. The default theme uses it, and your theme and custom pages can import any part of it from vuesho/ui/<path>:
import { Callout } from "vuesho/ui/components/callout";
import { DocsLayout } from "vuesho/ui/layouts/docs";The modules follow the files of Fumadocs UI: a component has the same name, DOM, class names and props. A prop taking a node or a render function in React is a slot of the same name in Vue, and a hook is a composable of the same name. The slots prop of a layout in Fumadocs UI, which replaces its parts, is the named slots of the layout component here, in kebab-case like #nav-title. The components page lists the modules.
Layouts
A layout renders a content page with the navigation of your site. Each one is a component of vuesho/layouts/<name>, built on the module of the same name under vuesho/ui/layouts:
docs: the default. A sidebar on the left with the title, search and page tree, the page in the middle and its table of contents on the right.notebook: a navbar across the top of the page, with the sidebar under it.tabMode: "navbar"shows the tabs of root folders in the navbar.glass: a sidebar and header buttons that float over the page, with rounded corners and a blurred, translucent background.spacious: the page on a panel inside a frame of the card color, with a header above the page.flux: no navbar. A floating panel at the bottom of the screen holds the title, the tabs and the tools, and the sidebar opens from it.
The home layout has the navbar of your site and no sidebar, for landing pages.
Choosing a Layout
The default theme renders content pages with the docs layout. To use another layout, extend the base theme and set the layout as layouts.default of your theme:
import { baseTheme, defineTheme } from "vuesho/theme";
import NotebookLayout from "vuesho/layouts/notebook";
import type app from "../vuesho.config";
export default defineTheme<typeof app>({
extends: baseTheme,
layouts: { default: NotebookLayout },
});The base theme is the default theme without a layout for content pages. Extend it rather than the default theme, since a theme extending the default theme keeps the code of the docs layout in your site, even with another layouts.default. A theme on the base theme without layouts.default needs a layout for each source, or the site fails when it starts.
A layout under the key of a source renders the pages of that source only. With multiple sources, this theme renders the guides in the notebook layout and the API reference in the docs layout:
import { baseTheme, defineTheme } from "vuesho/theme";
import DocsLayout from "vuesho/layouts/docs";
import NotebookLayout from "vuesho/layouts/notebook";
import type app from "../vuesho.config";
export default defineTheme<typeof app>({
extends: baseTheme,
layouts: { default: NotebookLayout, api: DocsLayout },
});Your site loads the code of the layouts your theme imports, so the code of the other layouts is in no page.
The flux layout animates with motion-v, which isn't installed with Vuesho. Install it in a site that imports the flux layout: npm install motion-v.
Layout of a Page
layout in the frontmatter of a page names the layout of layouts of your theme that renders it, in place of the layout of its source. The default theme has page, the content in the home layout, with the navbar of the site and without a sidebar:
---
title: Credits
layout: page
---Your theme adds names of its own, like layouts: { landing: () => import("./Landing.vue") } for layout: landing. A plugin can set layout with transformPage, like for the pages of a folder.
A page whose layout names no layout of the theme fails: when the site starts for layout in the frontmatter, and when the page renders for a layout a plugin sets. With a schema that lists the names, like layout: z.enum(["page", "landing"]), defineTheme<typeof app>() checks the keys of layouts against them. With the built-in schema, layout is any string, so any name is a key of layouts.
Landing Pages
The home layout renders its default slot under the navbar of your site. Wrap a custom page in it for a landing page, and do the same in the components of views and in the layouts of your own that don't use a docs layout:
<script setup lang="ts">
import HomeLayout from "vuesho/layouts/home";
import { Card, Cards } from "vuesho/ui/components/card";
</script>
<template>
<HomeLayout>
<main class="mx-auto w-full max-w-(--fd-layout-width) px-4 py-12">
<h1 class="mb-6 text-2xl font-semibold">Acme Docs</h1>
<Cards>
<Card title="Quick Start" href="/docs/quick-start">Create your first site.</Card>
<Card title="Theme" href="/docs/theme">Change the UI of your site.</Card>
</Cards>
</main>
</HomeLayout>
</template>src/pages/index.vue is at /, where it wins over content/index.md. Put the docs under a prefix with toFumadocsSource({ baseDir: "docs" }), so they start at /docs.
Layout and Page Props
A layout takes layoutProps, the props of its layout, and pageProps, the props of its page. They are typed by the layout, so a prop of another layout is a type error, and they can hold components and functions. To set them, write a layout of your own that renders the layout with them. This one renders the content pages in the notebook layout, with a logo as the title of its navbar:
<script setup lang="ts">
import type { ContentPage } from "vuesho/client";
import NotebookLayout from "vuesho/layouts/notebook";
import Logo from "./Logo.vue";
defineProps<{ page: ContentPage }>();
</script>
<template>
<NotebookLayout
:page="page"
:layout-props="{ tabMode: 'navbar', nav: { title: Logo } }"
:page-props="{ tableOfContent: { style: 'clerk' } }"
/>
</template>import { baseTheme, defineTheme } from "vuesho/theme";
import DocsPage from "./DocsPage.vue";
export default defineTheme({
extends: baseTheme,
layouts: { default: DocsPage },
});ContentPage is a content page of any source. layoutProps win over the layout props of the config, which set what every layout shares, like the links of the navbar. pageProps win over the data of the page, like the full of its frontmatter. The home layout takes layoutProps too.
Sidebar of One Folder
The sidebar shows the page tree of the language, with every source. layoutProps.tree replaces it, and selectTreeRoot() of vuesho/page-tree gives the tree of one folder, like the baseDir of a source:
<script setup lang="ts">
import { computed } from "vue";
import { usePageTree, type ContentPage } from "vuesho/client";
import { selectTreeRoot } from "vuesho/page-tree";
import DocsLayout from "vuesho/layouts/docs";
defineProps<{ page: ContentPage }>();
const pageTree = usePageTree();
const tree = computed(() => selectTreeRoot(pageTree.value, "docs"));
</script>
<template>
<DocsLayout :page="page" :layout-props="{ tree }" />
</template>The same path works in every language. A path without a folder throws, with the folders of the tree in the message.
To replace a part of a layout, like the title of the navbar or the table of contents, give a component to its slot. For a change the props and slots of a layout don't cover, copy the layout into your project with the CLI and edit it.