jldec/pub-server

JavaScript static site generator and editor (pre react & gatsby)

pub-server

Docs

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 https://jldec.github.io/pub-doc/. 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

installation

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

npm install -g pub-server

usage

• 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 README.md 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]
opts:
  -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

credits

Major dependencies include:

• express
• marked
• handlebars
• browserify
• chokidar
• socket.io
• passport

npm ls will list them all.

pub-server's Issues

markdown fragments in sub-directories

hi, am wondering if it's possible to point pub at a directory and have it parse sub directories, generating a navigation tree automatically??

Thanks

David

endless redirect in docker container

hey, thanks for your great project!

i have some weird issue trying to run this inside a docker container:

directory layout:

README.md

startup

pub -E -W -K

output

pub-server v1.10.2
source /var/app/*.{md,hbs}
pub-pkg-jquery
pub-theme-doc
pub-pkg-highlight
pub-pkg-font-awesome
starting up http://localhost:3001
listening on port 3001

so far so good, but if i try to access the page i get:

$ curl localhost:3001
Found. Redirecting to /readme

$ curl localhost:3001/readme
Found. Redirecting to /

this leads to an endless redirect.

somehow it works perfectly on my local machine (osx), so i guess the problem has todo with case sensitive filesystems inside the container (linux) or something like that...

i tried it with a readme.md but happens to be the same

install fails with node v4.x

try to install with node v4

pub-server npm install will show errors building socket.io like the following:

> [email protected] install /Users/hello/pub/server/node_modules/socket.io/node_modules/engine.io/node_modules/ws/node_modules/bufferutil
> node-gyp rebuild

  CXX(target) Release/obj.target/bufferutil/src/bufferutil.o
In file included from ../src/bufferutil.cc:16:
../node_modules/nan/nan.h:261:25: error: redefinition of '_NanEnsureLocal'

how to paginate?

hi.

i setup a blog: http://pub.smt.biz.st ,but how to paginate?

feature query: commit changes to git?

I found pub-server looking for a compromise between a git-backed static site generator, and an web-editable site, like a wiki.

In other words, I want to be able to edit markdown in a git repository and have it published to a static site when I push to origin; however, I also want to allow others to edit this site and have changes committed, without forcing them to learn about git and all the rest.

Something like a markdown wiki would be nice, although the full features of a wiki aren't mandatory, just something non-technical users can use without a lot of frustration.

I've looked at some other solutions; site generators are typically editorless, and more full blown blogging software is (IMO) just too complicated and fragile, when all you really want to end up is some static content on a web server.

pub-server looks intriguing in that it almost seems to do just what I wanted, if without the wiki-style histories and page indexes. I've cloned the code, and running pub.js from within allows me to edit the markdown in the repo! But saving does not appear to commit the changes, and although I've looked through the source of pub-server and some of the pub-* dependencies, I don't see evidence that it can currently do that.

There is I think a pluggable way to publish content changes, the pub-src-* packages, am I correct? However I can't see anything which commits to git. Tentatively it looks like it will publish to the filesystem, github pages, redis, and a JSON API over HTTP. The info in these sub packages are a bit terse, so I'm a bit sketchy about that.

So my question is, is what I want to do achievable now with pub-server, or if not, with not to much effort for someone reasonably familiar with Javascript and the NodeJS toolchain?

Thanks.

Is Windows still not supported?

I would like to try this. I'm running Win7. This would be nice -

A 1-click installer which eliminates the need to pre-install node.js and 
use the command-line is coming soon. Fixes for Windows support are also a high priority.

What goes wrong when I try to install on Windows?