Content Sources
Combine collections, and load pages from anywhere.
A content source is the list of files the site builds its pages from. toFumadocsSource() of a collection is a source, and createSite() in vuesho.config.ts takes one source, or several by key.
Multiple Sources
Pass an object to combine sources. defineCollections() with type: "doc" defines a collection of pages only. The sources share one tree of files, and toFumadocsSource({ baseDir }) puts the files of a collection in a folder of that tree, so their URLs start with the folder:
import { createSite } from "vuesho/config";
import { defineCollections, defineDocs } from "vuesho/content";
import { pageSchema } from "vuesho/schema";
import { z } from "zod";
const docs = defineDocs({ dir: "content/docs" });
const blog = defineCollections({
type: "doc",
dir: "content/blog",
schema: pageSchema.extend({ date: z.string() }),
});
export default createSite({
docs: docs.toFumadocsSource({ baseDir: "docs" }),
blog: blog.toFumadocsSource({ baseDir: "blog" }),
});content/docs/install.md is now at /docs/install, and content/blog/hello.md at /blog/hello. Two sources can't have a file at the same path, so give each its own baseDir, or keep one source at the root.
The key of a source is the type of its pages: a plugin tells them apart with page.type === "blog", and the theme gives the pages of each type their layout. page.data.date of a blog page is a string. With one source, page.type is undefined.
Sidebar of Multiple Sources
The sources share one page tree, so the sidebar of the docs lists the folders of every source, like a blog folder. A meta.json keeps a folder out of it:
With the docs at the root,
"!blog"in their rootmeta.jsonleaves the folder of the blog out:content/docs/meta.json { "pages": ["...", "!blog"] }With the docs in their own folder, like
baseDir: "docs", make that folder a root folder. The sidebar of a page of the docs then lists that folder only:content/docs/meta.json { "title": "Docs", "root": true }
Blog shows how to list the posts on a page of their own.
Content Options
The second argument of createSite() configures the content loader:
import { createSite } from "vuesho/config";
import { defineDocs } from "vuesho/content";
import { defineI18n } from "vuesho/i18n";
const docs = defineDocs();
export default createSite(docs.toFumadocsSource(), {
i18n: defineI18n({ languages: ["en", "cn"], defaultLanguage: "en" }),
});i18nsets the languages of the site, see Internationalization.loaderPluginsare plugins of the Fumadocs content loader.- Other options, like
slugs,urlandpageTree, are passed to the Fumadocs content loader as they are.
An option that the loader doesn't have is a type error.
Custom Sources
A custom source lists pages from anywhere, and a plugin renders them. Each file has a path, which sets its URL, and data, which is page.data of its page. baseDir puts its files in a folder of the tree of files, like the one of a collection, and the type Source gives page.data its fields:
import { createSite, type Source } from "vuesho/config";
import { defineDocs } from "vuesho/content";
const docs = defineDocs();
const releases = [
{ version: "0.2.0", notes: "<p>Custom content sources.</p>" },
{ version: "0.1.0", notes: "<p>The first release.</p>" },
];
const changelog: Source<{ pageData: { title: string; html: string }; metaData: {} }> = {
baseDir: "changelog",
files: releases.map(({ version, notes }) => ({
type: "page",
path: `${version}.md`,
data: { title: `v${version}`, html: notes },
})),
};
export default createSite({ docs: docs.toFumadocsSource(), changelog }).plugins({
name: "site:changelog",
getPageBody(page) {
// `page.data` of the changelog has `html`
if (page.type === "changelog") return { html: page.data.html };
},
});/changelog/0.2.0 shows the HTML of its release. The pages of collections render without a plugin, while a page of a custom source fails to render when no plugin returns its body.
Data Files
import.meta.glob() of Vite puts files into the build of vuesho.config.ts. With eager: true, a source lists its pages from JSON files, like the releases of the example above:
import type { Source } from "vuesho/config";
interface Release {
version: string;
notes: string;
}
const releases = import.meta.glob<Release>("./releases/*.json", { eager: true, import: "default" });
const changelog: Source<{ pageData: { title: string; html: string }; metaData: {} }> = {
files: Object.values(releases).map(({ version, notes }) => ({
type: "page",
path: `changelog/${version}.md`,
data: { title: `v${version}`, html: notes },
})),
};To read YAML files, import them as text with query: "?raw" and parse each with a YAML parser, like the yaml package.
Don't read files with node:fs in vuesho.config.ts. It works during the build, but a serverless host runs the server without the files of your project, so the server fails to start there.
Fetching at Build Time
vuesho.config.ts can fetch a source with a top-level await:
import { createSite, type Source } from "vuesho/config";
const response = await fetch("https://cms.example.com/posts");
const posts: { slug: string; title: string; html: string }[] = await response.json();
const cms: Source<{ pageData: { title: string; html: string }; metaData: {} }> = {
files: posts.map((post) => ({
type: "page",
path: `${post.slug}.md`,
data: { title: post.title, html: post.html },
})),
};
export default createSite(cms).plugins({
name: "site:cms",
getPageBody: (page) => ({ html: page.data.html }),
});The source is static, so its pages are generated at build time. The request runs when vuesho.config.ts runs: during the build, and again when a server deployment starts. To read the posts again without a new deployment, make the source dynamic.
Dynamic Sources
When files is a function, the source is dynamic. The server reads it when the site starts, and its pages render on demand instead of at build time, so the site needs a server to deploy. The routes that list pages, like the sitemap and the search index, render on demand too. What Renders on Demand explains how a route and the route rules change this.
import { createSite, type Plugin, type SourceFile } from "vuesho/config";
interface Post {
slug: string;
title: string;
html: string;
}
async function listPosts(): Promise<SourceFile[]> {
const response = await fetch("https://cms.example.com/posts");
const posts: Post[] = await response.json();
return posts.map((post) => ({
type: "page",
path: `${post.slug}.md`,
data: { title: post.title, html: post.html },
}));
}
const postsPlugin: Plugin = {
name: "site:posts",
getPageBody(page) {
// a plugin typed `Plugin` fits any site, so it checks the fields of `page.data`
if ("html" in page.data && typeof page.data.html === "string") return { html: page.data.html };
},
routes({ createApi }) {
// read the posts again, after a change in the CMS
createApi({
path: "/api/refresh",
POST: async () => {
await this.revalidateLoader();
return new Response("Refreshed");
},
});
},
};
export default createSite({ files: listPosts }).plugins(postsPlugin);With multiple sources, only the pages of the dynamic sources render on demand, and the pages of the others are still generated at build time. A static preset of Nitro has no server, so its build reads a dynamic source once and generates its pages.
Revalidation
The server keeps the files it read until one of these reads the source again:
staleTimeof the source, in milliseconds: the first request after it passes reads the files again. WithstaleTime: 0, every request reads them.this.revalidateLoader()reads every dynamic source now, or the one of a source key:this.revalidateLoader("posts").this.invalidateLoader()marks them stale, and the next request reads them.
export default createSite({ files: listPosts, staleTime: 60_000 });A request reads the content as it was when the request started, so its page, its page tree and the routes it reads agree while a source changes. The requests that start after a read have the new files.
Check a secret in the request of a refresh route before you call revalidateLoader(), so that only your CMS can trigger it.
Caching
A page of a dynamic source with a staleTime has a Cache-Control header, for the page and for the data the browser loads for it: public, s-maxage=60 for a staleTime of 60 seconds. A CDN in front of the server then keeps the page as long as the server keeps the files. A staleTime of 0 sends no header, since every request reads the files. A route of your own reads the header of a page with this.getCacheControl(page).