Folder meta

Configure a sidebar group with a meta.ts file beside its pages — set the group's title, icon, order, and the order of the pages nested inside.

Every folder in your content tree becomes a sidebar group. Drop a meta.ts beside its pages to control how that group looks and how its children are ordered. It’s entirely optional: without one, the group’s label is the humanized folder name and its pages sort by index, numeric prefix, then alphabetically.

Defining meta

Export a defineMeta object for a fully typed config. Place the file at the root of the folder it configures — guides/meta.ts configures the Guides group:

import { defineMeta } from "blume";

export default defineMeta({
  title: "Guides",
  icon: "book-open",
  order: 2,
  collapsed: false,
  pages: ["configuration", "theming", "deployment"],
});

Every field is optional — set only what you want to override.

Blume only reads meta.ts files from folders your content covers: one under a folder your content exclude globs skip, or outside every include glob, is never imported. With root: "." and exclude: ["src/**"], an unrelated src/lib/meta.ts is left alone.

A meta.ts outside every include glob is still ignored when its folder is a sidebar group, like a reference’s tag folder on a site whose include lists only guides/**. Blume warns about that one as BLUME_META_OUTSIDE_INCLUDE: add an include glob that reaches the folder, such as "api/**/*.{md,mdx}", so Blume reads it.

Fields

The pages array lists children by slug — the folder or file name with its numeric prefix and any parentheses stripped (so 01-quickstart.mdx is "quickstart"). Each listed child takes its position in the array as its order (0, 1, 2, …). Children you leave out still appear, sorted by their own order: an index page stays first, a child with a sidebar.order, a numeric prefix, or its own meta.ts order sorts by that number among the listed ones, and a child with none of these goes after them. List every child when the array should be the whole order. An entry that names no page or folder in the group orders nothing, so Blume warns about it as BLUME_META_UNKNOWN_PAGE, at its line in meta.ts, and suggests the slug it most likely means.

The array orders pages among pages and groups among groups, but it doesn’t interleave the two where loose pages list above groups: at the top of the sidebar (and of each tab section), and in any group with a flat subgroup, whose header would otherwise seem to own the pages after it. There, pages: ["advanced", "intro"] still lists the intro page above the advanced group.

How groups render — flat headers, collapsible disclosures, or drill-in panels — defaults to the sidebar-wide navigation.sidebar.display; set display here to override it for this group alone. A folder’s index page can also set it from frontmatter, which wins over meta.ts — see per-group overrides.

Generated groups

An OpenAPI, AsyncAPI, or GraphQL reference names and orders its tag groups from the spec. To change one, add a meta.ts in the folder the tag’s pages publish under: with the reference at /api, api/pets/meta.ts in your content folder configures the Pets group. The fields it sets replace the generated ones, and the rest keep their generated values, so a meta.ts that sets only title keeps the tag’s place in the spec’s order.

Computed meta

Because meta.ts is a real module, you can compute the meta — pass a function (sync or async) instead of an object to build it at scan time. Handy for ordering pages from an external source:

import { defineMeta } from "blume";

export default defineMeta(async () => ({
  title: "Guides",
  pages: await orderFromCms(),
}));

Ordering within a group

The pages array sets the order of a group’s children, and it wins over a listed page’s own sidebar.order or a listed subfolder’s own order. Anything it omits falls back to each page’s frontmatter sidebar.order, then the file system (an index page first, then numeric prefixes, then alphabetical). For the full sidebar precedence — including an explicit config sidebar — see Navigation › Ordering.

To group pages without adding a URL segment, you don’t need a meta.ts at all: use a parenthesized folder name — see Pages › Group folders.

Internationalization

Under i18n, folder meta resolves per locale: put a meta.ts under fr/guides/ to order the French group independently. Without one (or a shared meta.$.ts, below), the French group mirrors the fallback locale’s meta.ts.

For folder meta that’s identical in every language, add a $ marker so one file serves all locales without duplication:

docs/guides/meta.$.ts   (folder meta applied to every locale)

A locale-specific meta.ts still overrides the shared meta.$.ts for that language.

Where to next