Skip to Content
Vuesho

Theme

Give content pages their layouts and views their components, and change the icons and styles of your site.

The theme module is the UI of your site. Create src/theme.ts, and default-export a theme that builds on the default one:

src/theme.ts
import { BookOpen, Rocket } from "@lucide/vue";
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import type app from "../vuesho.config";

export default defineTheme<typeof app>({
  extends: defaultTheme,
  icons: { BookOpen, Rocket },
});

defineTheme<typeof app>() checks the theme against the pages of your site, with a type-only import of vuesho.config.ts. A site without vuesho.config.ts calls defineTheme() without the type, and a site without TypeScript can do the same in src/theme.js.

A site without a theme module uses the default theme. Vuesho picks up src/theme.ts, src/theme.js, src/theme/index.ts or src/theme/index.js, in this order. To use another file, set the theme option of the Vite plugin:

vite.config.ts
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho({ theme: "src/docs-theme.ts" })],
});

The theme module runs on the server and in the browser, so use browser APIs only in onMounted() and event handlers.

Layouts

The pages of your content render with the layouts of layouts. A content page renders with the layout its layout names, else with the layout of its source, else with layouts.default. The keys are:

  • default, for the content pages without a layout of their own. The default theme sets it to the docs layout.
  • The key of a source, for its pages, like blog for the pages of { blog: blog.toFumadocsSource() }.
  • A name of layout, which a content page sets in its frontmatter. The default theme has page.

A value is a component, or a function that imports it, so only the pages that render it load its code. This theme renders the posts of the blog source with a layout of its own, and the other content pages with the docs layout of the default theme:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import type app from "../vuesho.config";

export default defineTheme<typeof app>({
  extends: defaultTheme,
  layouts: { blog: () => import("./layouts/BlogPost.vue") },
});

The layouts of Vuesho, like the notebook layout, are components of vuesho/layouts/<name>: Choosing a Layout sets one for the content pages, or for the pages of one source.

Typed Layouts

A layout receives one prop, page. PageOf<typeof app, "blog"> of vuesho/client is its type, which is what the browser receives for a page of that source. The layout renders the content of the page with page.Content:

src/layouts/BlogPost.vue
<script setup lang="ts">
import type { PageOf } from "vuesho/client";
import type app from "../../vuesho.config";

defineProps<{ page: PageOf<typeof app, "blog"> }>();
</script>

<template>
  <article>
    <h1>{{ page.pageData.title }}</h1>
    <p>{{ page.data.date }}</p>
    <component :is="page.Content" />
  </article>
</template>

The layout renders the whole page, so this one has no navbar. Wrap it in the home layout for the navbar of your site, like the layout of the Blog guide.

A content page has:

  • type: the key of its source, undefined with one source.
  • url: its path, without the base path.
  • data: the frontmatter of its file, validated by its schema, as JSON: a Date is a string.
  • pageData: its title, description and full, the githubUrl of its file, its lastModified date, noindex and layout, and what plugins change with transformPage.
  • toc: its table of contents.
  • Content: its content, which renders with the Markdown components it imports.

With defineTheme<typeof app>(), a key that isn't a source or a name of layout, and a layout whose page is of another source, are type errors. layouts.default receives the pages of every source.

A site whose theme has no layout for a source, neither its own nor layouts.default, fails when it starts, with an error that names the source. A functional component in layouts declares its props, since a function without them is read as a function that imports a component.

A page shows once its data, its content and its layout have loaded.

Views

A view is a page that a plugin adds, and views gives each view its component, by the name of the view. The component of a view comes from the theme of its plugin, which you add to extends, see Plugins with UI. To change it, give the view a component of your own in views:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import releasesTheme from "acme-releases/theme";
import type app from "../vuesho.config";

export default defineTheme<typeof app>({
  extends: [defaultTheme, releasesTheme],
  views: { releases: () => import("./Releases.vue") },
});

The component receives the page as its page prop, typed by PageOf<typeof app, "releases">. A view has type, url, params (the values of the params of its path), pageData, and props, what the view of the plugin returned. A view without a component fails to render, with an error that names the view.

Icons

icons maps the icon names of pages, folders and navbar links to Vue components, like the icons of @lucide/vue. See Icons of the content. The base theme has gitlab and bitbucket, the icons of the repository link of site.git.

Building on Other Themes

A theme is used as written: it has the UI of the default theme because it names the default theme in extends. extends takes a theme or a list of themes, where a later theme wins over an earlier one. Your theme adds to them:

  • layouts, views and icons merge by name, and your entries win.
  • head lists and the components of each slot are joined, with yours last. A slot that replaces a part renders the last component.
  • The enhanceApp of each theme runs, yours last.
  • Root and NotFound replace theirs.

There are two themes to build on:

  • The default theme, vuesho/theme/default, renders content pages with the docs layout.
  • The base theme, baseTheme of vuesho/theme, is the default theme without a layout for content pages: its Root, NotFound and search dialog. A theme with another layout extends it, so the code of the docs layout isn't in your site.

To change the default theme beyond its options, copy it into your project with the CLI: npx @vuesho/cli add theme.

A Theme Without extends

A theme without extends doesn't build on the default theme: its layouts and Root aren't in the JavaScript of your site. Your theme then gives the layouts of content pages, like layouts.default, and NotFound for a URL without a page:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import type app from "../vuesho.config";
import NotFound from "./NotFound.vue";
import Page from "./Page.vue";

export default defineTheme<typeof app>({
  NotFound,
  layouts: { default: Page },
});

A source without a layout fails when the site starts, a view without a component fails to render, and so does a URL without a page when the theme has no NotFound, each with an error that names what is missing. The build renders 404.html, so it fails without NotFound.

The stylesheet is still the default one until you create src/theme.css.

Slots

slots puts components in the slots of the root component and of the layouts. A slot takes one component, or a list rendered in order:

src/theme.ts
import { defineAsyncComponent } from "vue";
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import Banner from "./Banner.vue";

export default defineTheme({
  extends: defaultTheme,
  slots: {
    "layout-top": Banner,
    "page-bottom": defineAsyncComponent(() => import("./Comments.vue")),
  },
});

These slots add to a place, and render every component they get, in order:

SlotWhere
layout-top, layout-bottomAbove and below every page.
sidebar-banner, sidebar-footerThe top and the bottom of the sidebar.
toc-header, toc-footerAbove and below the table of contents.
page-actionsA row under the description of a page.
page-bottomAfter the content of a page.

The docs, notebook and flux layouts have every slot. The glass and spacious layouts have no slot in their sidebar. A layout of your own can have slots of other names.

A component of a slot is an ordinary component: it reads the page with usePage(), and renders nothing on a page where it has nothing to show. Use defineAsyncComponent() for a component that only some pages render, so the other pages don't load it. The slots join the components of every theme, in the order of extends, then yours.

Replacing a Part

The other slots replace a part of the UI. A slot of this kind renders one component, the last one given, so your theme replaces the part of the themes it extends:

  • search-dialog: the dialog of the search.
  • In every layout: nav-title, color-mode-switch, search-trigger-sm, search-trigger-full, language-select and language-select-text.
  • In some layouts: header, sidebar, sidebar-trigger, sidebar-collapse-trigger (notebook), sidebar-drawer (glass and spacious), actions (spacious) and tab-dropdown (flux).
  • In the page of a layout: breadcrumb, footer (the links to the previous and next pages), toc, toc-popover (docs, notebook and spacious) and toc-dropdown (spacious).

The component receives the props of the part it replaces, like the class the layout gives the title of the navbar:

src/NavTitle.vue
<script setup lang="ts">
defineProps<{ class?: string }>();
</script>

<template>
  <a href="/" :class="$props.class"><img src="/logo.svg" alt="Acme" /></a>
</template>
src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import NavTitle from "./NavTitle.vue";

export default defineTheme({
  extends: defaultTheme,
  slots: { "nav-title": NavTitle },
});

A replacement sidebar reads and changes the state of the sidebar, like whether it is open, with useSidebar() of the sidebar module of its layout, such as vuesho/ui/layouts/docs/slots/sidebar.

Slots in a Template

The slots of slots are slots of the layout components too. A layout of your own that renders a layout of Vuesho fills them with templates. A template comes after the components of slots, so it wins in a slot that replaces a part:

src/DocsPage.vue
<template>
  <DocsLayout :page="page">
    <template #page-actions>
      <a :href="`/print${page.url}`">Print</a>
    </template>
    <template #footer>
      <a href="/feedback">Send feedback</a>
    </template>
  </DocsLayout>
</template>

Root

Root is the root component around every page of the app, custom pages too. The default one gives the UI the search, the color mode and the language switch, and has the slots layout-top and layout-bottom. A Root of your own wraps the default one to keep those.

Head and App Setup

head adds tags to every page, like a script that runs before the first paint. Your tags come after those of the themes you extend:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";

export default defineTheme({
  extends: defaultTheme,
  head: [{ tag: "script", attrs: { src: "/analytics.js", defer: true } }],
});

For tags that depend on the page, use head in vuesho.config.ts: its tags and those of plugins win over the theme's by key. The tags of the theme are in the head of every page, so when a page replaces one, like a title, the next page has the theme's tag again.

enhanceApp receives the Vue app and the router, to register Vue plugins and the hooks of the router. It runs on the server and in the browser, before the app loads its first page, and the app awaits it:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import { createPinia } from "pinia";

export default defineTheme({
  extends: defaultTheme,
  enhanceApp({ app }) {
    app.use(createPinia());
  },
});

An async enhanceApp can import a module first, like a Vue plugin that reads window when it loads:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";

export default defineTheme({
  extends: defaultTheme,
  async enhanceApp({ app }) {
    if (!import.meta.env.SSR) {
      const { default: plugin } = await import("./browser-plugin");
      app.use(plugin);
    }
  },
});

Router Hooks

router.beforeEach() adds a hook that runs before a page shows, and router.afterEach() adds a hook that runs once the app shows a page. Both hooks receive to and from, the routes of the next page and of the page on screen, like the guards of Vue Router. from is undefined for the page the app starts at. Each call returns a function that removes the hook.

A beforeEach hook returns false to cancel the navigation, or a path of the site to go there instead. It runs on the server and in the browser, for the first page too. When it sends the first page to another path, the server answers with a redirect. The first page can't be cancelled, since the app has no page to stay on: a hook that cancels checks that from is defined.

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";

export default defineTheme({
  extends: defaultTheme,
  enhanceApp({ router }) {
    // the pages of version 1 moved to /v2
    router.beforeEach((to) => {
      if (to.path.startsWith("/v1/")) return to.path.replace("/v1/", "/v2/");
    });
  },
});

A beforeEach hook can also return a function, which is Vuesho's own: the router calls it when the navigation shows its page, to apply what the hook loaded. A navigation that a later one replaced never calls it.

An afterEach hook runs in the browser, once the page is in the DOM and scrolled, so it can read the new content. It runs for the page the app starts at too, once the app is mounted. An analytics script counts that page when it loads, so this hook counts the pages of later navigations only:

src/theme.ts
import { defineTheme } from "vuesho/theme";
import defaultTheme from "vuesho/theme/default";
import { trackPageView } from "./analytics";

export default defineTheme({
  extends: defaultTheme,
  enhanceApp({ router }) {
    router.afterEach((to, from) => {
      if (from) trackPageView(to.href);
    });
  },
});

Styles

The stylesheet of your site is src/theme.css, or src/theme/style.css, when the file exists. It replaces the default stylesheet, and it is loaded with or without a theme module.

Colors

The colors of the UI are CSS variables like --color-fd-primary, and each color preset is a stylesheet of the package. To pick another one, import it in src/theme.css:

src/theme.css
@import "vuesho/style/ocean.css";

The color presets are neutral, black, vitepress, dusk, catppuccin, ocean, purple, solar, emerald, ruby, aspen and shadcn. To change single colors, set their variables after the import:

src/theme.css
@import "vuesho/style/neutral.css";

:root {
  --color-fd-primary: hsl(160, 84%, 39%);
}

.dark {
  --color-fd-primary: hsl(158, 64%, 52%);
}

Fonts

The UI uses the font variables --font-sans and --font-mono. To use another font, load it with @font-face in src/theme.css and set the variable:

src/theme.css
@import "vuesho/style/neutral.css";

@font-face {
  font-family: "Inter";
  src: url("./fonts/Inter.woff2") format("woff2");
  font-weight: 100 900;
  font-display: swap;
}

:root {
  --font-sans: "Inter", sans-serif;
}

A url() relative to the stylesheet is a file of your project, like src/fonts/Inter.woff2, which the build includes.

Tailwind CSS

The stylesheets above are compiled, so a site needs no Tailwind CSS. They have the classes that the UI uses, and only those. To use other classes in your pages and components, or in a copy of the UI, install Tailwind CSS and add its Vite plugin:

npm install -D tailwindcss @tailwindcss/vite
vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
import vuesho from "vuesho/vite";

export default defineConfig({
  plugins: [vuesho(), tailwindcss()],
});

Then write the stylesheet from its sources: Tailwind CSS, a color preset, and the styles of the UI. Tailwind CSS now generates the classes of the UI together with yours:

src/theme.css
@import "tailwindcss";
@import "vuesho/css/ocean.css";
@import "vuesho/css/preset.css";