Configuration
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.
// postdoc.config.js
export default {
contentPath: './docs',
appSettings: {
name: 'My project'
}
};Config resolution
PostDoc uses the first of these files that exists:
postdoc.config.mjspostdoc.config.cjspostdoc.config.js(an ES module whenpackage.jsonhas"type": "module")postdoc.config.mtspostdoc.config.tspostdoc.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".
// 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:
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.testsanddirectories.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/:
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_modulesandtestdirectories 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 toapidocs.ejs.createUrl(filePath)- returns the URL of the page for a file. It receives the file's path relative tosource, and the URL also decides where the page is written. By default, the URL is that path with.htmlinstead of.js: withsource: './lib',lib/commands/run.jsbecomes/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 totrueto make pages only of the files that have a comment with a@nametag. Defaults tofalse: 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:
options- marked options, plus switches for the built-in extensions. All of them are on by default:useCodeGroups,useTables,useAlertContainers,useMermaid,useStorymaps,usePlaygrounds,useNotebooksanduseMathExpressions. Heading ids get the prefix set ingfmHeadingId.prefix(postdoc-by default), andgfmHeadingId: falseturns them off.syntaxHighlight- code blocks are highlighted with Shiki in a light and a dark theme,github-light-high-contrastandgithub-dark-high-contrastby default, whose colours pass the page checks. Settheme.lightandtheme.darkto change them, or setsyntaxHighlighttofalseto turn highlighting off.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, alightand adarkone, 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, orfloating, the map filling the storymap with the steps scrolling over it. Defaults todocked.projection-mercator, orglobe, 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, andscale, in kilometres, orimperialornautical.sources,layers,timeline,legendandpopups- data to put on every map, and what explains it.map- other options of the MapLibre map, such asminZoom,maxZoomormaxBounds.center,zoom,bearing,pitchandbounds- the view before a step sets one.
The storymap reference describes each of them.
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 alogo, 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 }.navandapiNav- the sidebars of the guide and of the API reference. An item withchildrenis a section that opens and closes.github,editLinkandversions- 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 totrueto use regular page loads.enable_prefetch- set totrueto fetch a page when the pointer moves over a link to it.
Search
The build creates a Pagefind search index. The pagefind
setting controls it:
enabled- set tofalseto skip the index. Defaults totrue.outputDir- where the index goes, relative to the output directory. Defaults topagefind.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 tofalseto leave them out. Defaults totrue.llms.description- a line about the site, at the top ofllms.txt. Defaults toappSettings.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 asport.plugins- extra Vite plugins.publicDir- overridesdirectories.vitePublic. A relative path is relative to the project's folder.rootandlogLevel.
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:
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 tochrome.headless- runs browsers without a window. Defaults totrue.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:
enabled- set tofalseto skip page checks. Defaults totrue.ignore- glob patterns of page URLs to skip, e.g.'/legacy/**'.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.readyTimeout- how long to wait, in milliseconds, for a page to finish rendering before it is checked. A page is ready when itsonRendercallbacks have finished. Defaults to10000.a11y- accessibility checks with axe, orfalseto turn them off:context- the CSS selector to check. Defaults tohtml.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, orfalseto skip that.attributeandvaluesay how to switch it: by default,data-theme="dark"on<html>, as the default theme does. Withattribute: 'class', the value is added as a class, and withattribute: null, nothing is set on the page. In Chrome and Edge, theprefers-color-scheme: darkmedia query matches too.
keyboard- the keyboard check, orfalseto 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 totrue.ignore- CSS selectors of elements to leave out of the report.maxStops- how many Tab stops to check on a page. Defaults to1000.
toggles- opens menus, dialogs and panels with the keyboard, orfalseto skip it. It finds buttons witharia-expanded="false",aria-haspopup,popovertargetorcommandfor, and closed<details>. It fails when Enter doesn't open one oraria-expandeddoesn'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 to20.
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 tofalseto skip it:spacing- set tofalseto skip the text spacing.resize- set tofalseto skip the larger text.ignore- CSS selectors of elements to leave out of the report.
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 tofalseto skip it. It's skipped whensession.disable_spais 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.