Build and preview
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
npx postdoc buildThe build empties the output folder, then writes:
- an
.htmlfile 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.txtand a copy of each Markdown page,index.mdbesideindex.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:
npx postdoc previewpostdoc 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:
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.