1 |
|
2 | # pub-server <br>
|
3 | [Docs](https://jldec.github.io/pub-doc/)
|
4 |
|
5 | **pub-server**, or **pub** for short is an HTML site-generator and editor entirely written in JavaScript.
|
6 |
|
7 | The following use-cases are supported
|
8 |
|
9 | - Command-line tool for generating static websites
|
10 | - Web server for previewing generated HTML locally
|
11 | - Web server deployed on a PaaS like Heroku
|
12 |
|
13 |
|
14 | 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.
|
15 |
|
16 | 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.
|
17 |
|
18 | 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](https://jldec.github.io/pub-doc/pub/?page=%2F) button at the top right.
|
19 | Feel free to play around - in this instance, your changes will not be recorded.
|
20 |
|
21 | Other examples include a [presentation theme](https://github.com/jldec/pub-sample-deck), a [flexbox design](https://github.com/jldec/pub-theme-brief), and a [blog](https://blog.pubblz.com/)
|
22 |
|
23 |
|
24 | ![](/screenshots/screen1.png)
|
25 |
|
26 | ![](/screenshots/screen.png)
|
27 |
|
28 | ![](/screenshots/screen2.png)
|
29 |
|
30 | ## installation
|
31 |
|
32 | **pub-server** requires node.js v6 or later running on MacOS or Linux.
|
33 |
|
34 | ``` bash
|
35 | npm install -g pub-server
|
36 | ```
|
37 |
|
38 | ## usage
|
39 |
|
40 | - `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.
|
41 |
|
42 | - `pub -O` generates .html and other static files (including generator + editor) to `./out`.
|
43 |
|
44 | - `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/
|
45 |
|
46 | - `pub -h` shows the usage info below:
|
47 |
|
48 | ```
|
49 | pub-server v2.0.0
|
50 |
|
51 | usage: pub [opts] [dir]
|
52 | opts:
|
53 | -p, --port <port> server port [3001]
|
54 | -t, --theme <name> theme module-name or dir, repeatable (default: [])
|
55 | -o, --output-path <dir> output dir [./out]
|
56 | -O, --output-only output html, scripts, static files and exit
|
57 | -r, --root <prefix> generate /prefix urls, "." means path relative
|
58 | -s, --static <dir> static dir, repeatable, supports <dir>,<route> (default: [])
|
59 | -S, --static-only <dir> serve only static files from <dir> (default: [])
|
60 | -C, --config show config and exit
|
61 | -I, --ignore-config ignore pub-config file
|
62 | -P, --pages show pages and templates and exit
|
63 | -w, --watch-pkgs also watch inside packages
|
64 | -W, --no-watch disable watcher entirely
|
65 | -K, --no-sockets no websockets
|
66 | -E, --no-editor website only, no editor support
|
67 | -m, --minify minify scripts
|
68 | -d, --dbg enable scriptmaps and client-side debug traces
|
69 | -D, --debug node --debug (server and client-side)
|
70 | -B, --debug-brk node --debug-brk (server and client-side)
|
71 | -h, --help output usage information
|
72 | ```
|
73 |
|
74 | ## credits
|
75 |
|
76 | Major dependencies include:
|
77 |
|
78 | - [express](https://expressjs.com/)
|
79 | - [marked](https://github.com/markedjs/marked)
|
80 | - [handlebars](https://handlebarsjs.com/)
|
81 | - [browserify](https://github.com/browserify/browserify) and [browserify-middleware](https://github.com/ForbesLindesay/browserify-middleware)
|
82 | - [chokidar](https://github.com/paulmillr/chokidar)
|
83 | - [socket.io](https://socket.io/)
|
84 | - [passport](https://github.com/jaredhanson/passport)
|
85 |
|
86 | `npm ls` will list them all.
|