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