What is Postdoc?

Page content:

Postdoc turns a folder of Markdown files into a static website. It was made for documentation, but it works for any site whose content lives in Markdown.

You write pages in Markdown and design them with HTML layouts. There is no front-end framework to learn: layouts are plain HTML with EJS tags wherever you need data, and the result is static HTML that any web server can host.

What you get

  • Markdown with extras: syntax highlighting, tabbed code groups, callouts, tables with merged cells, Mermaid diagrams and math. See Markdown.
  • Layouts in plain HTML: EJS templates run at build time with full access to Node.js. See Layouts.
  • Navigation without reloads: a small script swaps pages in place, and the site still works with JavaScript turned off. See Navigation without reloads.
  • Search: every build creates a Pagefind search index. See Search.
  • Offline support: with vite-plugin-pwa installed, one setting turns the site into a progressive web app that keeps working offline. See Offline support.
  • API reference from your code: JSDoc comments become pages. See API docs from JSDoc.
  • Accessibility checks on every page: postdoc test builds the site, checks each page in a real browser and tries it with the keyboard, with no test files to write. See Testing.
  • Vite underneath: a fast dev server, optimised builds, and Vite plugins when you need them.

How it works

  1. Postdoc compiles each Markdown file to HTML.
  2. It picks a layout based on where the page sits in the content folder, and renders the layout with the page's content and front matter.
  3. Vite bundles the CSS and JavaScript the layouts reference, and writes the site to the output folder.
  4. Pagefind indexes the finished pages for search.

A layout with no Markdown page behind it becomes a page of its own, which is handy for a home page or a 404 page.

Is Postdoc a good fit?

Postdoc suits you if you want to only use HTML and CSS, keep pages light, and check your documentation pages in your CI service the way you check your code.

If you want interactive components written in Vue or React inside your Markdown, a framework-based tool such as VitePress or Docusaurus may be a better match.

Next steps

Edit this page on GitHub