Skip to Content
Vuesho

Configuration

Configure your site, its head tags, navbar and default plugins in vuesho.config.ts.

vuesho.config.ts at the project root configures your site. The file is optional: without it, the site renders the pages of content/ with the defaults.

vuesho.config.ts
import { createSite } from "vuesho/config";
import { defineDocs } from "vuesho/content";

const docs = defineDocs();

export default createSite(docs.toFumadocsSource()).config({
  site: {
    name: "Acme Docs",
    description: "Guides and reference for Acme.",
    baseUrl: "https://docs.acme.dev",
  },
});

The file can also be vuesho.config.mts, vuesho.config.js or vuesho.config.mjs.

Content and Plugins

createSite() takes your content sources and their options, like the languages of the site. Then .plugins() adds plugins, and .config() sets the options on this page. Each call is optional, in this order:

vuesho.config.ts
export default createSite(docs.toFumadocsSource(), { i18n })
  .plugins(myPlugin)
  .config({ site, head, ui });

The site takes its types from the content: page.data has the fields of its source, and plugins and options receive the pages and languages of the site. Other files read these types with a type-only import of vuesho.config.ts, like PageOf<typeof app, "blog"> in a layout. The pages of your own are custom pages, .vue files of src/pages.

Site

Name and Description

site.name shows in the navbar and after the title of every page, like Installation | Acme Docs. site.description is the meta description of pages without a description of their own.

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  site: {
    name: "Acme Docs",
    description: "Guides and reference for Acme.",
  },
});

URL

site.baseUrl is the full URL of your deployed site. It adds a canonical link to every page, and makes the URLs in llms.txt and the alternate links of translated pages absolute. A sitemap lists full URLs, so /sitemap.xml and its link in robots.txt exist with site.baseUrl only, and the build says so without it. Without site.baseUrl, pages have no canonical link and the other URLs are relative.

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  site: {
    baseUrl: "https://docs.acme.dev",
  },
});

Language

site.lang is the language tag of a site without i18n, like "en-US". It defaults to "en". The tag is the <html lang> of every page, and sets the direction of the text in <html dir>: a tag like "ar" makes the site right to left.

A site with languages sets these per language in site.languages, see Languages.

Repository

site.git adds a link to your repository to the navbar, and an "Edit on GitHub" link to each Markdown page.

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  site: {
    git: {
      user: "acme",
      repo: "docs",
      branch: "dev",
      dir: "apps/docs",
    },
  },
});
  • provider is the host of the repository: "github" by default, "gitlab" or "bitbucket".
  • url is the address of a self-hosted instance, like "https://git.acme.dev". It defaults to the public instance of the host.
  • branch is the branch the edit links open, "main" by default.
  • dir is the folder of your site in the repository. Set it when your site isn't at the root of the repository, like in a monorepo.

With the options above, the edit link of content/guide.md is https://github.com/acme/docs/blob/dev/apps/docs/content/guide.md. On GitLab, the same link is https://gitlab.com/acme/docs/-/blob/dev/apps/docs/content/guide.md.

The navbar shows GitHub with githubUrl of the layout props. For GitLab and Bitbucket, it shows a link with the icon of the host, from the icons of the base theme. The edit link of a page is githubUrl of its page data, whatever the host. A page of a custom source has an edit link when its plugin answers getPageFile.

head adds tags to the <head> of every page. attrs take HTML attribute names. A tag html or body sets attributes of that element, like { tag: "html", attrs: { class: "docs" } }.

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  head: [
    { tag: "link", attrs: { rel: "icon", href: "/favicon.svg" } },
    { tag: "meta", attrs: { name: "theme-color", content: "#0a0a0a" } },
  ],
});

An href or src that is a path of your site, like /favicon.svg above, gets the base path.

For tags that depend on the page, pass a function. It receives the path and lang of the page, its pageData (the title and description of a content page, a view or a custom page), and the page of a content page.

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  head({ pageData }) {
    if (!pageData?.title) return;
    return [{ tag: "meta", attrs: { property: "og:title", content: pageData.title } }];
  },
});

A tag with a key replaces the tag of the same key from plugins, defaults and the head of the theme. The keyed tags are title, a meta by its name, property or http-equiv, the canonical link, and an alternate link by its hreflang. The attributes of html and body replace those of the same name, one by one. Other tags are all kept.

By default, each page has its title, description, Open Graph tags (og:title, og:description, og:site_name), <meta name="robots" content="noindex"> for a page with noindex, and <html lang dir>. With site.baseUrl, it also has a canonical link and og:url, and a translated page has an alternate link per language, plus x-default for the default language. The not found page has none of these, since it shows at every URL without a page.

The tags of a page are sent with it. When the reader follows a link, the app swaps the tags of the previous page for those of the new one, so the title, the Open Graph tags and the canonical link always match the page on screen.

To change the format of titles, return a title tag. It replaces the default one:

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  head: ({ pageData }) => [
    { tag: "title", content: pageData.title ? `${pageData.title} – Acme` : "Acme" },
  ],
});

Layout Props

ui.layoutProps sets the props that every layout shares, like the links of the navbar. The theme picks the layout of the pages of each source.

  • nav: the title of the navbar and the url it links to. They default to site.name and the home page. enabled: false hides the navbar, and transparentMode makes its background transparent: "always", "top" (at the top of the page only) or "none", the default.
  • links: links in the navbar, each with text, url and an optional external. A link with type: "menu" has items, the links of its menu. A link with type: "icon" shows its icon alone, with label as its accessible name. A link with type: "button" shows as a button.
  • githubUrl: the GitHub link of the navbar, set by site.git.

The icon of a link is the name of a component in the icons of your theme, like an icon of the page tree. Without a component of that name, the icon is shown as text, like an emoji.

A link takes these options too:

  • active: when the link shows as the current page. "url", the default, matches its URL only, "nested-url" matches the pages under it too, and "none" never.
  • on: where the link shows. "nav" is the navbar, "menu" is the menu of the layout, like the sidebar of the docs layout or the menu of small screens, and "all", the default, is both.
  • secondary: a link of type: "icon", "button" or "menu" shows with the secondary links, which the layout places apart from the main ones. Icon links are secondary by default.

The other props:

  • colorModeSwitch: the switch of the color mode. enabled: false hides it, and mode: "light-dark-system" adds the choice of the system's mode to light and dark.
  • searchToggle: the search button. enabled: false hides it, and sm and full take hideIfDisabled, which hides the button of small screens or of large screens when the site has no search.
  • tabs: the tabs of the sidebar, or false for none. They default to the root folders of the page tree.
  • search: set by the search plugin, which configures the dialog with its own options.
vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  ui: {
    layoutProps: {
      links: [
        { text: "Blog", url: "/blog" },
        { text: "Discord", url: "https://discord.gg/acme", external: true },
      ],
    },
  },
});

On a site with languages, ui.layoutProps can be a function of the language, see Links per Language. Layout props are the same on every page of a language, so the browser loads them once. A difference for some pages, like other links in one folder, is written in your theme: a layout component reads the page with usePage().

Layout props are sent to the browser, so every value must be serializable: text, numbers, lists and plain objects. Props of one layout, and values like components, are props of the layout component in your theme.

Color Mode

The reader picks light, dark or the system's mode with the switch of the navbar. ui.colorMode.default sets the mode that applies until the reader picks one: "system", the default, "light" or "dark". This site starts dark:

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  ui: { colorMode: { default: "dark" } },
});

With fixed: true, every page has the default mode, and the reader can't change it: the layouts have no switch, the D key doesn't toggle the mode, and a pick the reader made before is ignored. This site is always light:

vuesho.config.ts
createSite(docs.toFumadocsSource()).config({
  ui: { colorMode: { default: "light", fixed: true } },
});

A script in each page applies the mode before the page shows, so the page doesn't flash in the other mode. The reader's pick is kept in localStorage, under the key vuesho-color-mode. Your components read and set it with useColorMode().

Default Plugins

Your site comes with a sitemap (with site.baseUrl), robots.txt, llms.txt and search. They come from recommendedPreset(), and each takes options, or false to leave it out:

vuesho.config.ts
import { createSite, recommendedPreset } from "vuesho/config";

createSite(docs.toFumadocsSource()).config({
  preset: recommendedPreset({
    sitemap: { path: "/sitemap-docs.xml" },
    robots: false,
    llms: { full: false },
  }),
});
  • sitemap.path: the URL of the sitemap, /sitemap.xml by default.
  • robots.sitemap: the sitemap URL listed in robots.txt, or false for none. It follows sitemap.path.
  • llms.path and llms.full: the URLs of llms.txt and llms-full.txt. Set full: false to skip llms-full.txt.

Set preset: [] to leave out every default plugin.

To use a plugin of your own in place of a default one, see Replacing a Default Plugin.

Leaving Pages Out

sitemap, llms and search take a filter. A content page that filter returns false for isn't listed by that plugin, while the page itself still renders. filter receives the pages of your site, typed by their schema. This config leaves out the pages with unlisted: true in their frontmatter:

vuesho.config.ts
import { createSite, recommendedPreset } from "vuesho/config";
import { defineDocs } from "vuesho/content";
import { pageSchema } from "vuesho/schema";
import { z } from "zod";

const docs = defineDocs({
  docs: { schema: pageSchema.extend({ unlisted: z.boolean().default(false) }) },
});

export default createSite(docs.toFumadocsSource()).config({
  preset: recommendedPreset({
    sitemap: { filter: (page) => !page.data.unlisted },
    llms: { filter: (page) => !page.data.unlisted },
    search: { filter: (page) => !page.data.unlisted },
  }),
});

How Options Merge

Plugins return head tags and layout props too. Your own options win, then plugins in the order you list them, then the default plugins. In layout props, lists like links concatenate, with your links first. See Merging Results for each hook.