Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time




pub-server, or pub for short is an HTML site-generator and editor written in JavaScript.

The following use-cases are supported

  • Command-line tool for generating static websites
  • Web server for previewing generated HTML locally
  • Web server deployed on a PaaS like Heroku

For users with node.js, pub-server provides a simple command-line utility which can render an HTML website from markdown in any directory. The generated output uses npm-installable themes and is fully customizable.

The generator+editor can also run in-browser, allowing non-technical users to edit and instantly preview the generated HTML, without first installing pub-server themselves.

To see this in action, check out the docs at The editor appears when you click on the edit button at the top right. Feel free to play around - in this instance, your changes will not be recorded.

Other examples include a presentation theme, a flexbox design, and a blog

Screenshot of pub-server editor with pub-theme-pubblog theme

Screenshot of pub-server editor with pub-theme-doc theme

Screenshot of pub-server editor with pub-theme-brief (flexbox) theme


pub-server requires node.js v6 or later running on MacOS or Linux.

npm install -g pub-server


  • pub (with no options) serves *.md in the current directory or looks for a pub-config.js. The default theme is useful for previewing GitHub files like this one. The server will watch for changes and update http://localhost:3001/ whenever markdown files or CSS or other static files are saved. On macOS, the url will be auto-opened in the browser; use pub -A to prevent this.

  • pub -O generates .html and other static files (including generator + editor) to ./out.

  • pub -S <dir> serves static files from any directory. It will mimic the behavior of GitHub Pages, looking for index.html files in folders, and redirecting from /folder-name to /folder-name/

  • pub -h shows the usage info below:

pub-server v2.11.3

usage: pub [opts] [dir]
  -A, --no-open            disable auto-open in browser (mac only)
  -p, --port <port>        server port [3001]
  -t, --theme <name>       theme module-name or dir, repeatable (default: [])
  -o, --output-path <dir>  output dir [./out]
  -O, --output-only        output html, scripts, static files and exit
  -r, --root <prefix>      generate /prefix urls, "." means path relative
  -s, --static <dir>       static dir, repeatable, supports <dir>,<route> (default: [])
  -S, --static-only <dir>  serve only static files from <dir> (default: [])
  -C, --config             show config and exit
  -I, --ignore-config      ignore pub-config file
  -P, --pages              show pages and templates and exit
  -w, --watch-pkgs         also watch inside packages
  -W, --no-watch           disable watcher entirely
  -K, --no-sockets         no websockets
  -E, --no-editor          website only, no editor support
  -m, --minify             minify scripts
  -d, --dbg                enable scriptmaps and client-side debug traces
  -D, --debug              node --debug (server and client-side)
  -B, --debug-brk          node --debug-brk (server and client-side)
  -h, --help               output usage information


Major dependencies include:

npm ls will list them all.