Build and preview

Page content:

postdoc build writes the finished site to the output folder, out/ by default. It's a folder of static files, so any web server or static host can serve it.

Build the site

sh
npx postdoc build

The build empties the output folder, then writes:

  • an .html file for each page, at the page's URL
  • the CSS and JavaScript that your layouts link, bundled by Vite into assets/
  • the files of your public folder, as they are
  • the search index, in pagefind/
  • llms.txt and a copy of each Markdown page, index.md beside index.html, for AI agents
  • a service worker and a web app manifest, when offline support is on

Drafts, pages with draft: true in their front matter, are left out.

Preview the build

Check the build locally before you publish it:

sh
npx postdoc preview

postdoc preview builds the site, then serves the output folder at the address it prints, http://localhost:4173 unless that port is taken. Unlike the dev server, it serves what your readers will get: bundled, with the search index written to disk, and without drafts.

Option What it does
--skip-build Serves the output folder as it is, without building it again
--port <port> Serves on this port, and fails if it's taken
--open [path] Opens the site in your browser, at the path if you give one
--host [host] Listens on your network too, so you can try the site on a phone

postdoc build, postdoc preview and postdoc test take --out-dir <dir> as well, to build somewhere else than the output folder and leave it as it is.

Host it in a subfolder

When the site lives in a subfolder of its domain, such as https://example.com/docs/, set base to that path:

postdoc.config.jsjs
export default {
  base: '/docs/'
};

Keep writing links and asset paths from the root of the site, like /guide/index.html: builds add the base path to them, in pages, layouts and stylesheets. postdoc preview serves the build from the base path, so you can check it before you deploy. The dev server keeps serving the site from the root.

In your own scripts, import.meta.env.BASE_URL holds the base path.

A 404 page

Most hosts show the 404.html at the root of the site for a URL that doesn't exist. A layout at layouts/404.ejs is published as /404.html, see Pages without Markdown.

Where to host it

  • GitHub Pages, with a workflow that tests the site before it deploys it.
  • Netlify, Vercel and Cloudflare Pages, which build the site for you each time you push.
  • Any other web server: copy the output folder to it. Nothing has to run on the server.

Edit this page on GitHub