Configuration

Page content:

Overview

PostDoc reads its settings from a configuration file in the project root, the directory you run postdoc from. Every setting has a default, so the file only needs the values you want to change. Nested objects are merged with the defaults, and arrays are appended to the default arrays.

js
// postdoc.config.js
export default {
  contentPath: './docs',
  appSettings: {
    name: 'My project'
  }
};

Config resolution

PostDoc uses the first of these files that exists:

  1. postdoc.config.mjs
  2. postdoc.config.cjs
  3. postdoc.config.js (an ES module when package.json has "type": "module")
  4. postdoc.config.mts
  5. postdoc.config.ts
  6. postdoc.json

A JavaScript or TypeScript file can export an object, or a function (sync or async) that returns one.

TypeScript files run with Node's built-in TypeScript support, which removes the types and needs no other package. It doesn't compile anything, so syntax that has to be compiled, such as enum, isn't supported, and imports of other TypeScript files need their extension: import sidebars from './sidebars.ts'. For full TypeScript, run PostDoc with a loader such as tsx: NODE_OPTIONS="--import tsx".

ts
// postdoc.config.ts
import type { PostdocConfig } from 'postdoc';

export default {
  contentPath: './docs'
} satisfies PostdocConfig;

Variables from a .env file are loaded into the environment. A string value written as ${NAME} is replaced with the NAME environment variable:

js
appSettings: {
  analyticsId: '${ANALYTICS_ID}'
}

Directories

Paths are relative to the project root.

Setting Default Contents
contentPath docs Markdown pages
baseDir postdoc The directory that holds layouts, includes and public files
directories.layouts layouts EJS layouts, relative to baseDir
directories.includes includes EJS partials, relative to baseDir
directories.vitePublic public Files copied to the output as they are, relative to baseDir
testsPath test Nightwatch tests run by postdoc test, in one directory or a list of them
outputPath out The build output

Older versions used directories.content, directories.tests and directories.output. PostDoc still reads them, with a warning. See Configurations of 0.3.0-preview4.

Base path

Set base when the site is served from a subfolder of its domain, such as https://example.com/docs/:

js
export default {
  base: '/docs/'
};

Builds then add the base path to every link and asset that starts with /, so pages and layouts keep linking to /guide/index.html. The dev server always serves the site from the root; postdoc preview serves the build from the base path. Defaults to /.

Theme

The theme setting picks the layouts, includes and public files that your project builds on. Your own files with the same names take precedence.

  • 'default' - the built-in theme. This is the default.
  • a path such as './my-theme' - a theme directory in your project. A value without a / is read as the name of a built-in theme.
  • null - no theme.

A configuration of 0.3.0-preview4, which had no themes, gets none.

Ignores

Each list holds anymatch patterns that are matched against absolute file paths:

  • ignore.pages - Markdown files that should not become pages.
  • ignore.layouts - layouts that should not become standalone pages. Pages can still use them.
  • ignore.apidocs - JavaScript files that should not become API pages. By default, node_modules and test directories are skipped.

API docs

PostDoc can turn JSDoc comments into pages. The apidocs setting configures it:

  • source - the directory with the JavaScript files. API pages are only generated when it is set.
  • layoutName - the layout for API pages, relative to the layouts directory. Defaults to apidocs.ejs.
  • createUrl(filePath) - returns the URL of the page for a file. It receives the file's path relative to source, and the URL also decides where the page is written. By default, the URL is that path with .html instead of .js: with source: './lib', lib/commands/run.js becomes /commands/run.html.
  • tags - functions that handle custom JSDoc tags, keyed by tag name. Each function receives the tag, the whole comment and the tags parsed so far, and may return an object to merge into the comment's data.
  • requireName - set to true to make pages only of the files that have a comment with a @name tag. Defaults to false: every file with a comment becomes a page.

A comment that starts with /*!, or has an @ignore tag, is left out, and a file whose comments are all left out makes no page. Each @example of a comment is in its example list as it is written, and in exampleHtml compiled as Markdown, which highlights a fenced code block.

Markdown

Markdown is compiled with marked. The markdown setting has three parts:

  1. options - marked options, plus switches for the built-in extensions. All of them are on by default: useCodeGroups, useTables, useAlertContainers, useMermaid, useStorymaps, usePlaygrounds, useNotebooks and useMathExpressions. Heading ids get the prefix set in gfmHeadingId.prefix (postdoc- by default), and gfmHeadingId: false turns them off.
  2. syntaxHighlight - code blocks are highlighted with Shiki in a light and a dark theme, github-light-high-contrast and github-dark-high-contrast by default, whose colours pass the page checks. Set theme.light and theme.dark to change them, or set syntaxHighlight to false to turn highlighting off.
  3. extensions - extra marked extensions.

Storymaps

The storymap setting holds the map settings every storymap of the site starts with, so a story only writes what is its own. A storymap's own settings replace them key by key, and any map setting can be given here:

  • style - the base map: a MapLibre style URL, a light and a dark one, which follow the site's colour scheme, or the style itself. A URL starting with / is a file of the site, in its public folder. By default, the free OpenFreeMap styles.
  • layout - docked, the steps beside the map, or floating, the map filling the storymap with the steps scrolling over it. Defaults to docked.
  • projection - mercator, or globe, which shows the Earth as a sphere when the map is zoomed out.
  • controls - the controls of the map: zoom, the zoom buttons, which are on by default, compass, and scale, in kilometres, or imperial or nautical.
  • sources, layers, timeline, legend and popups - data to put on every map, and what explains it.
  • map - other options of the MapLibre map, such as minZoom, maxZoom or maxBounds.
  • center, zoom, bearing, pitch and bounds - the view before a step sets one.

The storymap reference describes each of them.

javascript
export default {
  storymap: {
    style: {
      light: '/map-styles/bathymetry.json',
      dark: '/map-styles/bathymetry-dark.json'
    }
  }
};

App settings

Whatever you put in appSettings is available as the appSettings variable in every layout and include, and as {{ appSettings.name }} in Markdown. appSettings.name defaults to the name in your package.json.

The default theme reads these:

  • name - the site's name, in the header unless there's a logo, and in each title.
  • logo - an image for the header, such as /logo.svg, in place of the name.
  • headerNav - the links of the header and the footer: { title, url }.
  • nav and apiNav - the sidebars of the guide and of the API reference. An item with children is a section that opens and closes.
  • github, editLink and versions - the link to the repository, the link to edit each page, and the versions menu. See Themes.

Navigation

Pages switch without a full reload. The session setting controls it:

  • disable_spa - set to true to use regular page loads.
  • enable_prefetch - set to true to fetch a page when the pointer moves over a link to it.

The build creates a Pagefind search index. The pagefind setting controls it:

  • enabled - set to false to skip the index. Defaults to true.
  • outputDir - where the index goes, relative to the output directory. Defaults to pagefind.
  • options - Pagefind indexing options. By default, the index treats every page as English.

Pages for AI agents

Builds write an llms.txt at the root of the site, which lists its Markdown pages, and a copy of each one next to its HTML: /guide/index.md beside /guide/index.html. AI agents and other tools read them more easily than the pages.

  • llms.enabled - set to false to leave them out. Defaults to true.
  • llms.description - a line about the site, at the top of llms.txt. Defaults to appSettings.description, if there is one.

PWA

vite-plugin-pwa makes the built site work offline. Install it in the project, npm i -D vite-plugin-pwa, and set pwa.enabled to true to turn it on. The other pwa values are passed to the plugin as its options.

Vite

The vite setting passes these options to Vite:

  • server - dev server options, such as port.
  • plugins - extra Vite plugins.
  • publicDir - overrides directories.vitePublic. A relative path is relative to the project's folder.
  • root and logLevel.

Checks

postdoc check checks every link between the pages. When another site serves some paths of the domain, such as a blog or the docs of older versions, list them in check.ignoreLinks, as anymatch patterns of paths without the base path. Links to them are then left out:

js
export default {
  check: {
    ignoreLinks: ['/blog/**', '/v2/**']
  }
};

'/blog/**' matches /blog, /blog/ and every page below it.

Logger

  • logger.quiet - hides everything except errors.
  • logger.verbose - shows debug messages as well.
  • logger.noColors - turns off colours. PostDoc also respects the NO_COLOR environment variable.

Testing

The nightwatch setting configures the test command:

  • browser - the Nightwatch environment, or a list of them. Defaults to chrome.
  • headless - runs browsers without a window. Defaults to true.
  • parallel - runs test files in parallel.
  • watch - reruns the tests when they change.
  • config - the path to your own Nightwatch configuration file.

Page checks

The test command builds the site and checks every generated page in a real browser, without any test files. Configure it with the nightwatch.pageChecks property:

  1. enabled - set to false to skip page checks. Defaults to true.
  2. ignore - glob patterns of page URLs to skip, e.g. '/legacy/**'.
  3. widths - window widths, in CSS pixels, to check each page at, e.g. [1280, 390] to check the desktop and the phone layout. By default, pages are checked once, at the browser's window size.
  4. readyTimeout - how long to wait, in milliseconds, for a page to finish rendering before it is checked. A page is ready when its onRender callbacks have finished. Defaults to 10000.
  5. a11y - accessibility checks with axe, or false to turn them off:
    • context - the CSS selector to check. Defaults to html.
    • options - axe run options. By default, the WCAG 2.0, 2.1 and 2.2 level A and AA rules run.
    • darkMode - runs the contrast rules again with the page in dark mode, or false to skip that. attribute and value say how to switch it: by default, data-theme="dark" on <html>, as the default theme does. With attribute: 'class', the value is added as a class, and with attribute: null, nothing is set on the page. In Chrome and Edge, the prefers-color-scheme: dark media query matches too.
  6. keyboard - the keyboard check, or false to turn it off. It presses Tab through the page and fails on Tab stops that can't be seen, that don't show the focus or that have no name, on links to #, on elements that act as controls but can't take the focus, and when the focus gets trapped:
    • skipLink - also requires the first Tab stop to be a link to the main content. Defaults to true.
    • ignore - CSS selectors of elements to leave out of the report.
    • maxStops - how many Tab stops to check on a page. Defaults to 1000.
  7. toggles - opens menus, dialogs and panels with the keyboard, or false to skip it. It finds buttons with aria-expanded="false", aria-haspopup, popovertarget or commandfor, and closed <details>. It fails when Enter doesn't open one or aria-expanded doesn't follow, when the focus doesn't move into a modal dialog or leaves it, when axe or the keyboard check finds a problem in what opened, and when Escape doesn't close a dialog, a menu or an overlay or the focus doesn't go back to the button:
    • ignore - CSS selectors of buttons to leave out.
    • maxToggles - how many buttons to open on a page. Defaults to 20.
  8. text - fails when a box cuts off text with more space between lines, words and letters (WCAG 1.4.12), or with text twice as large (WCAG 1.4.4). Set it to false to skip it:
    • spacing - set to false to skip the text spacing.
    • resize - set to false to skip the larger text.
    • ignore - CSS selectors of elements to leave out of the report.
  9. navigation - follows a link that PostDoc shows without a reload, and fails when the new page isn't announced to screen readers, has another title than after a page load, or Tab doesn't start from the top of it. Set it to false to skip it. It's skipped when session.disable_spa is set.

The keyboard and toggles checks don't run in Safari, where Tab skips links by default.

Configurations of 0.3.0-preview4

PostDoc still reads the settings of 0.3.0-preview4, so a project written for it builds as it did. Each one is reported as a warning, by every command and by postdoc check, which still passes. Change them to keep the warnings away:

0.3.0-preview4 Now
directories.content contentPath
directories.output outputPath
directories.tests testsPath
apidocs.layout apidocs.layoutName
markdown.options.syntaxHighlight markdown.syntaxHighlight
_import() in a layout importModule()

A configuration without baseDir that sets any of directories.content, output, tests, layouts or includes is read as one of 0.3.0-preview4: its directories are relative to the project's folder, with that version's defaults, pages for the layouts and src/public for the public files, and it has no theme unless it sets one. Set baseDir: '.' and theme: null to keep it that way without the warning.