Getting started
Requirements
Postdoc needs Node.js 22.18 or newer.
Create a project
The quickest start is a new project with example pages:
npx postdoc init --name my-docs
cd my-docs
npm install
npm startnpm start runs postdoc run, the development server. Open the address it prints, http://localhost:5173 by default. When you save a page, a layout or an include, the browser reloads with the change.
To set up the current folder instead, use --name .. The folder has to be empty.
Look around
The new project contains:
| Path | What it is |
|---|---|
content/ |
Markdown pages. content/guide/usage/index.md becomes /guide/usage/index.html. |
src/layouts/ |
The layouts of the home and about pages. The other pages use the default theme's. |
src/css/ |
The styles of the home and about pages. |
src/public/ |
Files copied to the site as they are, such as the favicon. |
test/pages/ |
Page tests for postdoc test. See Your own tests. |
AGENTS.md |
How AI agents should work on the project and check their changes. See Working with AI agents. |
postdoc.config.js |
The configuration, with the links of the header and the sidebars. |
The header, the sidebars, the footer and the guide and API reference layouts come from Postdoc's default theme. To change one, put a file with the same name in src/layouts/ or src/includes/, and yours is used instead. Project structure explains how these folders are configured.
Add a page
Create content/guide/faq.md:
---
title: FAQ
---
# FAQ
## Can I use HTML in Markdown?
Yes. HTML in a Markdown file is kept as it is.Open http://localhost:5173/guide/faq.html to see it. The page uses the same layout as the other guide pages, because layouts are picked by folder. The guide's sidebar lists the links in appSettings.nav in postdoc.config.js, so add your page there:
{ title: 'FAQ', url: '/guide/faq.html' }Postdoc can also create the file for you, together with a page test in test/pages/:
npx postdoc create page --name /guide/faqTo start it as a draft, which the dev server shows and builds leave out until you remove draft: true from its front matter, add --draft. A draft gets no page test, as there's no page in the build for it to test.
Build the site
npm run buildThe site is written to out/. To check the build locally:
npm run previewWhen you're ready to publish, see Deployment.
Add Postdoc to an existing project
You don't need the example project to use Postdoc. In an existing project, install it:
npm install --save-dev postdocThe configuration file can also be written in TypeScript, as postdoc.config.ts. See The configuration file.
By default, Postdoc reads pages from docs/ and layouts from postdoc/layouts/. Create a layout in postdoc/layouts/index.ejs:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title><%= page.title %> | <%= appSettings.name %></title>
</head>
<body>
<main>
<h1><%= page.title %></h1>
<%- page.content %>
</main>
</body>
</html>and a page in docs/index.md:
---
title: Home
---
Welcome to the docs.Run npx postdoc run and open the address it prints. The layout applies to every page in docs/ that has no more specific layout; Layouts explains how layouts are picked.