Skip to Content
Vuesho

Content Hooks

Render the pages of a content source with a plugin.

A content source is a list of files: pages and meta.json files. The Markdown collections of your site are sources, and the built-in core:markdown plugin renders them. A source of your own, from an API, a CMS or a list in code, needs a plugin that renders its pages with content hooks.

This site has a changelog source next to its docs. Its pages come from a list in the config, and a plugin renders them:

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

const docs = defineDocs();

interface Release {
  title: string;
  description: string;
  date: string;
  html: string;
}

const releases = [
  { version: "0.2.0", date: "2026-11-01", notes: "<p>Custom content sources.</p>" },
  { version: "0.1.0", date: "2026-10-01", notes: "<p>The first release.</p>" },
];

const changelog: Source<{ pageData: Release; metaData: {} }> = {
  files: releases.map(({ version, date, notes }) => ({
    type: "page",
    path: `changelog/${version}.md`,
    data: { title: `v${version}`, description: "Release notes", date, html: notes },
  })),
};

export default createSite({ docs: docs.toFumadocsSource(), changelog }).plugins({
  name: "site:changelog",
  getPageBody(page) {
    if (page.type === "changelog") return { html: page.data.html };
  },
  getPageText(page) {
    if (page.type === "changelog") return `# ${page.data.title}`;
  },
  getPageLastModified(page) {
    if (page.type === "changelog") return new Date(page.data.date);
  },
});

The path of a file sets the URL of its page, so changelog/0.2.0.md is /changelog/0.2.0. Its data is page.data: title and description are the title and description of the page, and the plugin reads the rest.

With sources by key, page.type is the key of the source of a page. A plugin checks it and returns undefined for the pages of other sources, since the first result of a content hook wins. A plugin written in .plugins() has the types of the site, so page.type === "changelog" gives page.data the fields of Release. With one source, page.type is undefined. For sources that load files on the server, like from a CMS, see Content Sources.

Page Body

getPageBody gives the content of a page. It returns one of:

  • { html }: HTML rendered as it is, as the content of the page.
  • { module, load }: the URL of a module that the browser imports, whose default export is the content component, and load() to import the same module on the server. This is what core:markdown returns for a compiled Markdown file.

A page without a body, like a card whose fields are all in page.data, has an empty Content. The layout of its source in the layouts of the theme renders it from page.data, so give that source its own layout: without one, the page fails to render with an error that names its source, since layouts.default shows a body it doesn't have. To add data to the pages of a source, like the newer and older posts of a blog post, return it from transformPage.

Other Content Hooks

Each of these is optional. A page without a result has none of what the hook gives:

  • getPageToc returns the table of contents, a list of { title, url, depth }, for the docs layout.
  • getPageText returns the page as Markdown, for llms-full.txt.
  • getPageStructuredData returns the headings of the page and the text under each, for the search index.
  • getPageLastModified returns a Date, for the sitemap and the last update shown on the page.
  • getPageCreatedAt returns the Date the page was written, for feeds and blogs. core:markdown returns the date of the frontmatter.
  • getPageFile returns the path of the file of the page from the project root, like content/guide.md. With site.git, it gives the page its edit link.

getPageStructuredData returns headings, a list of { id, content }, and contents, a list of { heading, content } where heading is the id of the heading a text is under:

getPageStructuredData(page) {
  if (page.type !== "changelog") return;
  return {
    headings: [],
    contents: [{ content: page.data.html.replace(/<[^>]+>/g, "") }],
  };
},

Page Data

The browser receives the page data of each page, pageData. The core sets these fields of a content page:

  • title, description and full from page.data, and layout when page.data.layout is a string.
  • lastModified from the getPageLastModified hook, which the docs layout shows as the last update.
  • githubUrl, the link to edit the page, from the getPageFile hook and site.git.
  • noindex: true on a page shown in the fallback language, whose own page is the one of that language.

Then the transformPage hook of each plugin returns the fields it changes. Every plugin receives the same data, frozen, so the result doesn't depend on the order of plugins. A plugin can change any field, and undefined unsets one:

transformPage(_data, { path }) {
  // no edit link on the generated pages
  if (path.startsWith("/reference/")) return { githubUrl: undefined };
},

A field has one writer: two plugins that change the same field of a page fail with an error that names both. transformPage runs for every page: on a content page, env.page is the page; on a page of a page route, like a view, a custom page or the not found page, env.route is its route and env.page is undefined. The data of a page of a route starts with the data of the route, and the not found page of a language has noindex: true. Every value it returns is sent to the browser, so it must be serializable.

noindex: true keeps a page out of search engines with <meta name="robots" content="noindex">, and out of the sitemap and llms.txt. The page itself is still served, and the search of the site still finds it: to leave a page out of the search, use the filter of the search plugin:

transformPage: (_data, { path }) => (path.startsWith("/internal/") ? { noindex: true } : undefined),

PageData has the fields of the core and of the plugins, so a misspelled field is a type error. A plugin declares the fields it adds by declaration merging, in its module:

reading-time-plugin.ts
import type { Plugin } from "vuesho/config";

declare module "vuesho/config" {
  interface PageData {
    /** minutes to read the page */
    readingTime?: number;
  }
}

export const readingTimePlugin: Plugin = {
  name: "acme:reading-time",
  async transformPage(_data, { page }) {
    const text = page && (await this.getPageText(page));
    if (text) return { readingTime: Math.ceil(text.split(/\s+/).length / 200) };
  },
};

A layout then reads page.pageData.readingTime with its type.

Startup Hooks

Three hooks run once, when the site starts, in this order for all plugins:

  1. init runs before the content loads, so this.getPages() is still empty.
  2. configureLoader receives the options you pass to createSite(), and returns the options of the Fumadocs content loader it changes. An option you set yourself stays as you set it, and another option has one writer: two plugins that set it fail with an error that names both. The plugins of every plugin are combined, after your loaderPlugins.
  3. configure runs after the content loads, with every page available.
configure() {
  for (const page of this.getPages()) {
    if (!page.data.title) throw new Error(`${page.path} has no title`);
  }
},

A dynamic source is read again with this.invalidateLoader(), which doesn't run these hooks again.

From configure on, this.getLoader() is the content loader of Fumadocs, for what getPages() and getPage() don't do, like finding the page a link to a file leads to with getPageByHref(). Its URLs are encoded, as the loader makes them, so read pages with getPages() and getPage(), which give paths in the one form of the site.