Project structure

Page content:

Postdoc finds your files through a few settings in postdoc.config.js. Every setting has a default, so you only set the ones that differ.

Default structure

Without a configuration file, Postdoc expects these folders. Each has a setting that points Postdoc somewhere else:

my-project/
  • docs/ Markdown pages Setting: contentPath
  • postdoc/ What the pages are built with Setting: baseDir
    • layouts/ EJS layouts, which wrap the pages Setting: directories.layouts
    • includes/ Partials that the layouts share Setting: directories.includes
    • public/ Files copied to the site as they are Setting: directories.vitePublic
  • test/ Nightwatch tests Setting: testsPath
  • out/ The build, which Postdoc writes Setting: outputPath
  • package.json The project's name and its dependencies

Change the folders

A project created with postdoc init uses this configuration:

postdoc.config.jsjs
export default {
  contentPath: './content',
  baseDir: '.',
  testsPath: './test',
  outputPath: './out',

  directories: {
    layouts: './src/layouts',
    includes: './src/includes',
    vitePublic: './src/public'
  }
};

Paths are relative to the project root, the folder you run postdoc from. The paths under directories are relative to baseDir.

Old setting names

Version 0.3.0-preview4 configured these folders as directories.content, directories.tests and directories.output, relative to the project root, and had no baseDir. Postdoc still reads those settings, with a warning from every command and from postdoc check. Rename them to contentPath, testsPath and outputPath, and set baseDir: '.' and theme: null to keep the folders where they are. Configurations of 0.3.0-preview4 lists the other settings that changed.

URLs

A page's URL follows its path in the content folder, with .md replaced by .html:

File URL
docs/index.md /index.html
docs/guide/install.md /guide/install.html
docs/guide/index.md /guide/index.html

The dev server, like most hosts, also serves /guide/index.html at /guide/.

The configuration file

Postdoc uses the first of these files that it finds: postdoc.config.mjs, postdoc.config.cjs, postdoc.config.js, postdoc.config.mts, postdoc.config.ts or postdoc.json.

A JavaScript file can export an object, or a function that returns one. The function can be async:

js
import { readFile } from 'node:fs/promises';

export default async () => {
  const { version } = JSON.parse(await readFile('./package.json', 'utf8'));

  return {
    appSettings: { version }
  };
};

In TypeScript

A postdoc.config.ts runs with Node's built-in TypeScript support, so there's nothing to install. The settings are typed as PostdocConfig:

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

export default {
  appSettings: { sidebar: guide }
} satisfies PostdocConfig;

Node removes the types and runs the rest, without compiling it. So:

  • imports of other TypeScript files need their extension, ./sidebars.ts
  • types are imported with import type
  • syntax that has to be compiled, such as enum, namespaces and parameter properties, isn't supported, and neither are paths in tsconfig.json

Postdoc explains these errors when it loads the file. For everything TypeScript can do, run Postdoc with a loader such as tsx installed in the project:

sh
NODE_OPTIONS="--import tsx" npx postdoc build

Variables from a .env file are loaded into the environment. A string value that is exactly ${NAME} takes the value of the NAME environment variable:

postdoc.config.jsjs
export default {
  appSettings: {
    analyticsId: '${ANALYTICS_ID}'
  }
};

Configuration lists every setting.

Skip files

To keep Markdown files out of the site, list glob patterns under ignore.pages. The patterns are matched against absolute paths, so start them with **:

postdoc.config.jsjs
export default {
  ignore: {
    pages: ['**/drafts/**', '**/README.md']
  }
};

To hold back a single page for now, mark it as a draft in its front matter instead:

md
---
draft: true
---

The dev server shows drafts, and builds leave them out.

Vite settings

Postdoc runs on Vite. Vite options go under vite in the Postdoc configuration:

postdoc.config.jsjs
export default {
  vite: {
    server: {
      port: 3000
    },
    plugins: []
  }
};

Postdoc applies server, plugins, publicDir, root and logLevel. The dev server's port is set here, and postdoc run --port 5180 overrides it for one run.

Edit this page on GitHub