Plugins
Add routes, pages, content sources and build steps to your site.
A plugin is an object with a name and hooks. Add it to your site with .plugins():
import { createSite } from "vuesho/config";
import { defineDocs } from "vuesho/content";
const docs = defineDocs();
export default createSite(docs.toFumadocsSource()).plugins({
name: "site:status",
routes({ createApi }) {
createApi({
path: "/api/status",
GET: () => Response.json({ pages: this.getPages().length }),
});
},
});this in a hook is the context of the site: its config, its pages and helpers for URLs. Hooks run on the server only, so a plugin can read files, call APIs and use secrets.
To share a plugin, export a function that returns it, and type it with Plugin<C>. C is the site the plugin is added to, so its hooks receive the pages and languages of that site:
import type { AppShape, Plugin } from "vuesho/config";
export function statusPlugin<C extends AppShape>(options: { path?: string } = {}): Plugin<C> {
return {
name: "acme:status",
routes({ createApi }) {
createApi({ path: options.path ?? "/api/status", GET: () => Response.json({ ok: true }) });
},
};
}Each plugin needs a unique name. A site with two plugins of the same name fails to start. A key of a plugin that isn't a hook, like a misspelled one, is a type error in .plugins().
Hooks
Routes and requests:
routesadds API routes and views.deriveRoutesadds routes made from the final list of page routes of a language, see Derived Routes.middlewarehandles every request before the routes and pages, see Middleware.buildruns once when the site is built, see Build Hook.
Pages and layouts:
headadds tags to the<head>of a page, sent with the page.layoutPropsadds navbar links and other props of the layouts, per language.transformPagechanges the data of a page that the browser receives, like its title ornoindex.
A plugin with components ships them in a theme, and names it in theme: see Plugins with UI.
Content hooks, which render the pages of a content source:
getPageBodygives the content of a page.getPageTocgives its table of contents.getPageTextgives its Markdown, forllms-full.txt.getPageStructuredDatagives its headings and text, for search.getPageLastModifiedgives the date it last changed, for the sitemap and the page.getPageCreatedAtgives the date it was written, for feeds and blogs.getPageFilegives the path of its file, for the link to edit it.
initruns when the site starts, before the content loads.configureLoaderchanges the options of the Fumadocs content loader.configureruns when the site starts, after the content loads.
head and layoutProps take the same values as the head and ui.layoutProps options of your config:
createSite(docs.toFumadocsSource()).plugins({
name: "site:extras",
head: () => [{ tag: "meta", attrs: { name: "theme-color", content: "#0ea5e9" } }],
layoutProps({ lang }) {
return { links: [{ text: "Blog", url: this.localizePath(lang, "/blog") }] };
},
});Plugin Order
Plugins run in this order:
- Your plugins, in the order of
.plugins(). - The plugins of the preset.
- The built-in plugins, which you can't remove:
core:markdownrenders your Markdown collections,core:pagesserves the data of each page to the browser, andcore:siteadds the head tags of each page from its page data and yoursiteconfig.
When the site starts, each of these steps runs for every plugin before the next step: init, configureLoader, loading the content, configure, routes, then deriveRoutes. middleware and build run in plugin order too.
Merging Results
When several plugins return a value for the same hook, the results combine by hook:
head: tags with a key, liketitle, ametaby itsnameorproperty, and the canonical link, are unique, and the attributes ofhtmlandbodymerge one by one. Yourheadoption wins over plugins, and an earlier plugin wins over a later one. Other tags are all kept.layoutProps: your own options come first, then plugins in order. Objects merge deeply and lists concatenate, so every plugin can add links. For other values, the first defined value wins.transformPageandconfigureLoader: every plugin receives the same data and returns what it changes, so a field has one writer. Two plugins that change the same field fail with an error that names both. The options you pass tocreateSite()stay as you set them, and thepluginsof the loader are combined.- Content hooks, like
getPageBody: the first result that isn'tundefinedwins, so a plugin returnsundefinedfor a page it doesn't render.
core:site runs last, so a title or description tag from any plugin replaces its own.
Conditional Plugins
.plugins() skips false, null and undefined, and flattens lists:
createSite(docs.toFumadocsSource()).plugins(process.env.ANALYTICS === "1" && analyticsPlugin(), [
statusPlugin(),
changelogPlugin,
]);Default Plugins
The default plugins come from recommendedPreset(), in the preset option of .config(). Each has a key in its options:
sitemap, thecore:sitemapplugin, adds/sitemap.xml, on a site withsite.baseUrl.robots, thecore:robotsplugin, adds/robots.txt, with a link to the sitemap when there is one.llms, thecore:llmsplugin, adds/llms.txtand/llms-full.txt, in each language.search, thecore:searchplugin, adds a search index per language, searched in the browser.
Default Plugins of the config lists their options, and how to remove them.
Replacing a Default Plugin
Set the default plugin to false, then list your own:
import { createSite, recommendedPreset } from "vuesho/config";
import { defineDocs } from "vuesho/content";
import { mySearchPlugin } from "./search-plugin";
const docs = defineDocs();
export default createSite(docs.toFumadocsSource())
.plugins(mySearchPlugin())
.config({ preset: recommendedPreset({ search: false }) });The default plugins are exported too, as sitemapPlugin, robotsPlugin, llmsPlugin and searchPlugin. To list one yourself, like to run it before another plugin, set it to false in the preset first. Otherwise the site has the same plugin twice and fails to start.
Plugins from Fumapress for React
The hooks have the names and signatures of @fumapress/core, which Fumapress on Waku and Astro use. A plugin that uses only server-side hooks, like routes, middleware, content hooks and build, works on both.
The UI is different: the views of a plugin render with components of the theme, and every value sent to the browser is serializable.
Testing Plugins
createFetchHandler() of vuesho/server is the server of a site, without Vite. A test creates a site with your plugin and a custom source, and requests its routes. The handler needs a render function for pages, which a test of routes can stub:
import { createSite } from "vuesho/config";
import { createFetchHandler } from "vuesho/server";
import { expect, test } from "vitest";
import { statusPlugin } from "./status-plugin";
test("answers the status route", async () => {
const site = createSite({
files: [{ type: "page", path: "index.md", data: { title: "Home" } }],
}).plugins(statusPlugin());
const fetch = createFetchHandler({
site,
assets: { css: [], js: [] },
render: async () => ({ html: "" }),
});
const response = await fetch(new Request("http://localhost/api/status"));
expect(await response.json()).toEqual({ ok: true });
});The macros of vuesho/content are compiled by the Vite plugin, so a test lists its files instead of calling defineDocs().