Configuration

The docpensieve.config.mjs file, at the root of the project.

It is an ES module — hence .mjs, which Node reads as one whatever the project's package.json says. docpensieve.config.js works too, in a project whose package.json declares "type": "module"; with both files present, the build stops rather than pick one.

/** @type {import('@docpensieve/core').DocPensieveConfig} */
export default {
  projectName: 'My documentation',
  siteUrl: 'https://example.com/my-project',

  versions: [{ slug: 'v1.0', name: '1.0', folder: 'docs/v1.0', current: true }],

  outDir: 'dist',

  theme: {
    framework: 'tailwind',
    darkMode: 'class',
  },

  sidebar: 'auto',
  globalComponents: true,
  jsonld: { enabled: true },
};

The @type comment gives autocompletion and type checking in the editor without importing anything: the file stays readable even where DocPensieve only runs through npx. In a project that installs it as a dependency, defineConfig from @docpensieve/core does the same.

docpensieve init writes this file with every field in it — set to its default, or commented out with an example — so that it also tells you what you can change.

The fields

Images

logo: 'branding/logo.png',
favicon: 'branding/favicon.png',
socialImage: 'branding/social.png',

The paths start from the project root. Each image is copied into every version, under assets/, so that a version stays whole on its own branch.

• logo sits beside the project name, at the height of the header's text: a square image reads best there. Its alt stays empty, since the name follows it. It is also the logo of the organisation in the structured data.
• favicon is the icon of the browser tab: .ico, .png or .svg.
• socialImage is what a social network shows of a shared page, with its title and description. 1200 × 630 pixels is the usual size, and SVG is not read there. Those networks only read an absolute address, hence siteUrl.

A declared image that does not exist stops the build, naming the field.

Sitemap and feed

siteUrl: 'https://example.com',
sitemap: true, // the default
feed: true,

Once siteUrl is set, the build writes sitemap.xml at the root of the site: every page of every version, except a version in preparation, whose pages carry noindex. Each page is dated by its modified frontmatter, or failing that its date. sitemap: false turns it off.

robots.txt joins it when the site is served at the root of its domain. Search engines only read that file there: under a sub-path, it would be written for nobody — declare the sitemap to them directly.

feed: true writes feed.xml, an RSS feed of the pages of the current version that carry a date, newest first, and every page announces it in its head. It is off by default: most documentation pages carry no date.

Both list absolute addresses: asked for without siteUrl, they stop the build.

Search

search: true, the default, puts a search field in the header and builds a search page in each version, at /search/. The build writes the index of the version — the plain text of every page — and the search page already lists every page with its description.

The field is a plain form that leads to that page: it needs no script. The search page loads one of its own, of a few kilobytes, which filters the list as you type, best matches first, with an excerpt of each. Without JavaScript, the page stays the full list of pages.

The search page is kept out of search engines (noindex) and out of the sitemap. A page of your own at /search/ would take its place: the build refuses it, and search: false frees the address.

versions

versions: [
  { slug: 'v2.0', name: '2.0', folder: 'docs/v2.0', current: true },
  { slug: 'v1.0', name: '1.0', folder: 'docs/v1.0', archived: true },
],

theme

theme: {
  framework: 'tailwind',
  darkMode: 'class',
  tokens: { '--dp-accent': 'oklch(55% 0.2 250)' },
  css: '.dp-article h2 { letter-spacing: -0.01em; }',
  source: '@import "tailwindcss";',
},

The available tokens are listed in Themes.

Longer rules go in the theme/ folder, at the root of the project: every .css file in it is appended after css, in name order, and docpensieve dev picks up every change. Under the custom theme, init starts it with theme/custom.css.

authors

authors: 'authors.json',

Names a JSON file read in each version folder, describing the authors a page names in its frontmatter: a name, a biography, an avatar, a link.

Empty by default, and then a page still shows the names it gives, without the rest: the file enriches, it does not command. A version without the file shows the names alone, so describing the authors of a new version does not force a copy into the older ones. A file present but unreadable, or wrongly written, stops the build.

The file is not published. The avatars are, their path starting at the version folder so that they travel with it.

headerLinks

headerLinks: [
  { label: 'Blog', href: '/blog/' },
  { label: 'Examples', href: '/examples/', version: 'beta' },
  { label: 'Repository', href: 'https://github.com/me/my-project' },
],

Links of the header, beside the version switcher. A target starts from the root of the version — /blog/ — or is a full address. A relative target is refused: the header is on every page, and blog/ would mean something else on each.

version names the version a link leads to. Without it, each version links to its own page; with it, every version leads to that one — which is how a section written in one version only stays reachable from all of them. A version nobody declared stops the build.

On a narrow screen, the version switcher, the links and the search field move behind a menu button. It is a native element that opens without a script, like the version switcher itself.

A panel of links

An entry carrying columns opens a panel instead of leading anywhere:

headerLinks: [
  {
    label: 'Product',
    columns: [
      {
        title: 'Guide',
        items: [
          { label: 'Install', href: '/guide/installation/' },
          { label: 'Deploy', href: '/guide/deployment/' },
        ],
      },
      { items: [{ label: 'Repository', href: 'https://github.com/me/my-project' }] },
    ],
  },
],

A column may go without a title. Every link follows the rules above — absolute target, optional version. An entry cannot carry both href and columns: it either leads somewhere or opens a panel, never both.

The panel is declared here, not derived from the menu of the documentation: the two can stand side by side with different links, or the site can go without a sidebar and navigate from the header alone.

stickyHeader

stickyHeader: false,

The header holds to the top of the screen by default: the search field, the version switcher and the menu stay in reach wherever the reader is in the page.

false lets it scroll away with the page, which gives its height back to the text — on a phone held in one hand, that height is a third of what is visible. The anchors then stop reserving room for it: a link to a heading no longer leaves a blank band above it.

foldedSidebar

foldedSidebar: true,

Every category of the menu becomes a fold. The branch holding the page being read is open, the others closed: a menu of a hundred pages stops asking the reader to scroll past what does not concern them. It folds without a script.

A category that is also a page gains that page as its first entry: the handle of a fold cannot be a link as well without a click meaning two things.

Left to false, the menu shows whole, as before. On a narrow screen the whole menu folds above the content either way, since the column has nowhere to stand.

sidebar

'auto' builds the menu from the file tree: folders become categories, and the 01-, 02- prefixes set the order. To write it by hand, name a JSON file:

sidebar: 'sidebar.json',

It is read from each version's folder — docs/v1.0/sidebar.json — since each version has its own pages. A version without the file keeps the menu of its folders, so a menu written for a new version needs no copy in the older ones. The file holds an array of entries, kept in the order written:

[
  "/",
  { "label": "Guide", "page": "guide", "items": ["guide/installation", "guide/first-site"] },
  { "page": "reference/cli", "label": "Commands" },
  { "auto": "docpensieve" },
  { "label": "Repository", "href": "https://github.com/me/my-project" }
]

A page left out stays published: it is only absent from the menu. A path that names no page, a page listed twice, or an entry of no known kind stops the build, naming the file and the paths close to the one written. The file itself is not published.

baseUrl, and why you rarely write it

A siteUrl with a sub-path already gives it: https://example.com/my-project produces baseUrl: '/my-project/'. Writing it is only useful to depart from it.

The prefix is normalised with both its slashes. It is what prefixes every internal link: if it is wrong, every link is.

What is refused

Each one stops the build with a message and a hint, without a stack trace.

What is filled in automatically

If no version carries current, the first in the list becomes current. A single-version configuration therefore has nothing to specify — this field only starts to matter from the second version on.