Skip to Content
Vuesho

Content

Organize pages into collections, URLs and a sidebar.

Each Markdown file under content/ is a page, and the sidebar lists them for you.

Pages

The URL of a page comes from its file path:

  • content/index.md is /, and content/guide/index.md is /guide.
  • content/getting-started.md is /getting-started.
  • content/guide/install.md is /guide/install.

Files and folders starting with _ aren't pages, so they can hold partials next to your pages.

In the dev server, adding, renaming or removing a file updates the sidebar without a restart, and so does a change of frontmatter or of a meta.json.

Collections

A collection is a folder of pages and meta.json files. defineDocs() in vuesho.config.ts defines one, and toFumadocsSource() gives its pages to the site. A site without vuesho.config.ts has this config:

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

const docs = defineDocs();

export default createSite(docs.toFumadocsSource());

dir is the folder from the root of the project, content by default. A folder that doesn't exist fails the build. A file is in one collection: when two folders overlap, like content and content/blog, leave the inner folder out of the outer collection, or the file fails with the names of both collections. For a second folder, see Multiple Sources, and for a blog, Blog.

defineDocs() and defineCollections() are macros, like those of Fumadocs MDX. The build runs the macro calls of vuesho.config.ts with the statements their options use, and nothing else of the file. It compiles and validates each file with the options of its collection, and the server receives only the imports of the files. So a call follows two rules:

  • It is the value of a top-level const in vuesho.config.ts, like const docs = defineDocs({ ... }).
  • dir, files and type are literals, not variables or expressions.

A call that breaks a rule fails with its file, line and column, and so does a call in another file. Other options, like schema, can be variables and imports. A module that only the options import, like a Markdown plugin or zod, is not in the server bundle. In the dev server, a change of vuesho.config.ts or of a module its options import compiles the files of the collections again.

Leaving Files Out

files lists the pages of a collection with glob patterns, from dir. A pattern starting with ! leaves files out, so they aren't pages and the build doesn't include them:

vuesho.config.ts
const docs = defineDocs({
  docs: { files: ["**/*.md", "!archive/**"] },
});

meta.files does the same for the meta.json files. Files and folders starting with _ or ., and node_modules folders, are in no collection, whatever the patterns. A pattern can't have (, ) or \, which Vite reads differently in the dev server and in a build: match such a character of a name with ?, and write alternatives with braces, like {guide,api}/**.

Frontmatter Schema

Without a schema, the frontmatter of a page has the fields of Markdown, with title required, and page.data leaves out other fields. docs.schema takes any validator of Standard Schema, like Zod or Valibot. vuesho/schema exports pageSchema and metaSchema of Fumadocs as Zod objects, which need zod installed:

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

const docs = defineDocs({
  docs: { schema: pageSchema.extend({ author: z.string() }) },
});

export default createSite(docs.toFumadocsSource());

page.data.author is a string in plugins and layouts, without a type annotation. meta.schema validates the meta.json files the same way.

For a field that depends on the file, like the date of a post from its file name, schema can be a function that receives the file, as path (absolute) and source (its content), and returns the schema:

vuesho.config.ts
import { basename } from "node:path";

const blog = defineCollections({
  type: "doc",
  dir: "blog",
  schema: ({ path }) =>
    pageSchema.extend({ date: z.string().default(basename(path).slice(0, 10)) }),
});

A page or a meta.json is validated when it compiles, and page.data is the output of the schema, so a Date of the schema stays a Date on the server. A file that doesn't match its schema fails the build, and the dev server shows the error, with the file and each of its issues.

Compile Options

docs.markdown sets how the pages of a collection compile. It takes the compile options of the Vite plugin, and replaces them for the files of the collection, while the built-in plugins stay:

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

const blog = defineCollections({
  type: "doc",
  dir: "blog",
  markdown: { footnoteLabel: "Notes" },
});

In defineCollections(), markdown is an option of the call, next to dir. A file that a page imports, like a partial, is in no collection, so it compiles with the options of the Vite plugin.

Drafts

A page with draft: true in its frontmatter is a draft. vuesho dev shows it like any other page, and vuesho build leaves it out: it has no URL, and it is not in the sidebar, the search index, the sitemap or llms.txt. The output of the build has none of its content, so a draft is safe to commit.

content/next.md
---
title: Next Release
draft: true
---

draft is a field of the built-in schema and of pageSchema of vuesho/schema. With a schema that outputs draft, its output decides, and with a schema that leaves draft out, the frontmatter decides. A link to a draft is a broken link in the build.

Dates From Git

lastModified: true gives each page of a collection the date of the last commit that changed its file, as page.data.lastModified. The docs layout shows it below the page, and the sitemap lists it. A file that git doesn't track has no date.

vuesho.config.ts
const docs = defineDocs({ docs: { lastModified: true } });

In defineCollections(), lastModified is an option of the call, next to dir.

A shallow clone, which CI services often make, has only the latest commits, so a page last changed before them gets a wrong date. Clone the full history, like with fetch-depth: 0 of actions/checkout.

The sidebar lists the pages and folders of the content. Add a meta.json to a folder to set its title and the order of its pages:

content/meta.json
{
  "pages": ["index", "---Guides---", "guide"]
}
content/guide/meta.json
{
  "title": "Guide",
  "icon": "BookOpen",
  "defaultOpen": true,
  "pages": ["install", "configure", "..."]
}
  • title: the name of the folder in the sidebar.
  • icon: the icon of the folder.
  • defaultOpen: the folder is open in the sidebar by default.
  • pages: the pages and folders of the folder, in order.
  • root: the folder is a root folder.

Items of pages are file names without the extension, or folder names. "..." adds the pages that aren't listed, and "---Guides---" adds a separator with the text "Guides". "!name" leaves a page or a folder out of "...", so the sidebar doesn't list it, while the page still exists at its URL:

content/meta.json
{
  "pages": ["...", "!changelog"]
}

For other syntax of meta.json, see the page conventions of Fumadocs.

Root Folders

A folder with "root": true is a tab of the sidebar, for separate parts of the docs like a guide and an API reference. On a page in a root folder, the sidebar shows only the content of that folder, and a dropdown at its top switches to the other root folders:

content/guide/meta.json
{
  "title": "Guide",
  "root": true
}

Icons

The icon of a page or a folder is a name. Map the names to Vue components in the icons of the theme:

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

export default defineTheme({
  extends: defaultTheme,
  icons: { BookOpen, Rocket },
});

@lucide/vue is a package to install, and any Vue component works as an icon. A name without a component is shown as text, so an emoji works as an icon too:

content/index.md
---
title: Introduction
icon: 🚀
---