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.
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:
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.
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.
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.
createSite(docs.toFumadocsSource()).config({
site: {
git: {
user: "acme",
repo: "docs",
branch: "dev",
dir: "apps/docs",
},
},
});provideris the host of the repository:"github"by default,"gitlab"or"bitbucket".urlis the address of a self-hosted instance, like"https://git.acme.dev". It defaults to the public instance of the host.branchis the branch the edit links open,"main"by default.diris 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
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" } }.
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.
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:
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: thetitleof the navbar and theurlit links to. They default tosite.nameand the home page.enabled: falsehides the navbar, andtransparentModemakes its background transparent:"always","top"(at the top of the page only) or"none", the default.links: links in the navbar, each withtext,urland an optionalexternal. A link withtype: "menu"hasitems, the links of its menu. A link withtype: "icon"shows itsiconalone, withlabelas its accessible name. A link withtype: "button"shows as a button.githubUrl: the GitHub link of the navbar, set bysite.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 oftype: "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: falsehides it, andmode: "light-dark-system"adds the choice of the system's mode to light and dark.searchToggle: the search button.enabled: falsehides it, andsmandfulltakehideIfDisabled, which hides the button of small screens or of large screens when the site has no search.tabs: the tabs of the sidebar, orfalsefor 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.
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:
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:
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:
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.xmlby default.robots.sitemap: the sitemap URL listed inrobots.txt, orfalsefor none. It followssitemap.path.llms.pathandllms.full: the URLs ofllms.txtandllms-full.txt. Setfull: falseto skipllms-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:
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.