Merge branch 'master' of https://github.com/azerupi/mdBook

book-example/src/SUMMARY.md

@@ -5,6 +5,7 @@
     - [init](cli/init.md)
     - [build](cli/build.md)
     - [watch](cli/watch.md)
+    - [serve](cli/serve.md)
     - [test](cli/test.md)
 - [Format](format/format.md)
     - [SUMMARY.md](format/summary.md)

book-example/src/cli/serve.md

@@ -0,0 +1,33 @@
+# The serve command
+
+The `serve` command is useful when you want to preview your book. It also does hot reloading of the webpage whenever a file changes.
+It achieves this by serving the books content over `localhost:3000` (unless otherwise configured, see below) and runs a websocket server on `localhost:3001` which triggers the reloads.
+This preferred by many for writing books with mdbook because it allows for you to see the result of your work instantly after every file change.
+
+#### Specify a directory
+
+Like `watch`, `serve` can take a directory as argument to use instead of the
+current working directory.
+
+```bash
+mdbook serve path/to/book
+```
+
+
+#### Server options
+
+`serve` has four options: the http port, the websocket port, the interface to serve on, and the public address of the server so that the browser may reach the websocket server.
+
+For example: suppose you had an nginx server for SSL termination which has a public address of 192.168.1.100 on port 80 and proxied that to 127.0.0.1 on port 8000. To run use the nginx proxy do:
+
+```bash
+mdbook server path/to/book -p 8000 -i 127.0.0.1 -a 192.168.1.100
+```
+
+If you were to want live reloading for this you would need to proxy the websocket calls through nginx as well from `192.168.1.100:<WS_PORT>` to `127.0.0.1:<WS_PORT>`. The `-w` flag allows for the websocket port to be configured.
+
+-----
+
+***note:*** *the `serve` command has not gotten a lot of testing yet, there could be some rough edges. If you discover a problem, please report it [on Github](https://github.com/azerupi/mdBook/issues)*
+
+***note***: 

src/bin/mdbook.rs

@@ -62,7 +62,9 @@ fn main() {
                         .about("Serve the book at http://localhost:3000. Rebuild and reload on change.")
                         .arg_from_usage("[dir] 'A directory for your book{n}(Defaults to Current Directory when ommitted)'")
                         .arg_from_usage("-p, --port=[port] 'Use another port{n}(Defaults to 3000)'")
-                        .arg_from_usage("-w, --websocket-port=[ws-port] 'Use another port for the websocket connection (livereload){n}(Defaults to 3001)'"))
+                        .arg_from_usage("-w, --websocket-port=[ws-port] 'Use another port for the websocket connection (livereload){n}(Defaults to 3001)'")
+                        .arg_from_usage("-i, --interface=[interface] 'Interface to listen on{n}(Defaults to localhost)'")
+                        .arg_from_usage("-a, --address=[address] 'Address that the browser can reach the websocket server from{n}(Defaults to the interface addres)'"))
                     .subcommand(SubCommand::with_name("test")
                         .about("Test that code samples compile"))
                     .get_matches();
@@ -189,13 +191,15 @@ fn serve(args: &ArgMatches) -> Result<(), Box<Error>> {
     let mut book = MDBook::new(&book_dir).read_config();
     let port = args.value_of("port").unwrap_or("3000");
     let ws_port = args.value_of("ws-port").unwrap_or("3001");
+    let interface = args.value_of("interface").unwrap_or("localhost");
+    let public_address = args.value_of("address").unwrap_or(interface);
 
-    let address = format!("localhost:{}", port);
-    let ws_address = format!("localhost:{}", ws_port);
+    let address = format!("{}:{}", interface, port);
+    let ws_address = format!("{}:{}", interface, ws_port);
 
     book.set_livereload(format!(r#"
         <script type="text/javascript">
-            var socket = new WebSocket("ws://localhost:{}");
+            var socket = new WebSocket("ws://{}:{}");
             socket.onmessage = function (event) {{
                 if (event.data === "{}") {{
                     socket.close();
@@ -207,7 +211,7 @@ fn serve(args: &ArgMatches) -> Result<(), Box<Error>> {
                 socket.close();
             }}
         </script>
-    "#, ws_port, RELOAD_COMMAND).to_owned());
+    "#, public_address, ws_port, RELOAD_COMMAND).to_owned());
 
     try!(book.build());