Getting started

Page content:

Requirements

Postdoc needs Node.js 22.18 or newer.

Create a project

The quickest start is a new project with example pages:

sh
npx postdoc init --name my-docs
cd my-docs
npm install
npm start

npm 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:

content/guide/faq.mdmd
---
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:

postdoc.config.jsjs
{ title: 'FAQ', url: '/guide/faq.html' }

Postdoc can also create the file for you, together with a page test in test/pages/:

sh
npx postdoc create page --name /guide/faq

To 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

sh
npm run build

The site is written to out/. To check the build locally:

sh
npm run preview

When 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:

sh
npm install --save-dev postdoc

The 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:

postdoc/layouts/index.ejshtml
<!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:

docs/index.mdmd
---
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.

Edit this page on GitHub