Book struct

.travis.yml

@@ -5,6 +5,7 @@ language: generic
 env:
   global:
     - PROJECT_NAME=mdBook
+    - secure: l3/qEC4krRerllLQzni8j5AjngFi6pluWvBWj//1mJLoIEYwxlQ9mYxEdd9BqccWWFn3K0bVYCVC/64+tP6sRfLkZCe2gPUtwe7ITwCDbapUxmkiRObVJCs5yMQZt6idyhHUDKAXKgNCrusfI2BM3tKGBfRK7Cnn/R/7p/U9+q7D1sgJtUKp6ypVzK6A3jLNp3dFLFI19a5KmbZMVsaa7tOhtdDJjjr7ebsc9z7HMW5/OItiWU3FSauVQQlUMaCiEgFuIG7H7OnBAYWB/gNEtLuwfLqU9UjtWk/njNNRnmJ7m3y5HbQhv5H5F5mJUOq9XFlPLwPwyTeVztSGdQm6k8Pp2pgKBUjY27afBl9BWU+msmN6k0oXfhvIebiBPe/x2udiKeFik1xqOOEU1q9dF0sZiuPxCSM1n7tgWklJ8epgaRQaMPPQw9pO/2H5/ynHCJqBlw6WcdiqWtwAyyr/GEx62u/cg5IVkqb7KLmYsWzjS8wYG4CYs1eIxCw2xPZxP0FGuUXvxTBUPipFze6Z7FqxVauXtVe2D7c1P4738HZP660rmR0GYtHtKLny1QxCCK9sxd9JmcezFCSz4YeQ1od9xc0OzGJ2ullKNGizmGfYmgL6X8faNylLIEdaiHAcY16xV3L0g3fXL1Qg360UHQyj7GIv+0nqQnf+H9xRTTU=
 
 matrix:
   include:
@@ -57,6 +58,15 @@ matrix:
     - os: linux
       env: TARGET=x86_64-unknown-linux-musl CHANNEL=nightly
 
+  # Musl builds fail due to a bug in Rust (https://github.com/azerupi/mdBook/issues/158)
+  allow_failures:
+    - os: linux
+      env: TARGET=x86_64-unknown-linux-musl CHANNEL=stable
+    - os: linux
+      env: TARGET=x86_64-unknown-linux-musl CHANNEL=beta
+    - os: linux
+      env: TARGET=x86_64-unknown-linux-musl CHANNEL=nightly
+
 install:
   - export PATH="$PATH:$HOME/.cargo/bin"
   - bash ci/install.sh
@@ -65,10 +75,10 @@ script:
   - bash ci/script.sh
 
 after_success:
-  - test $TRAVIS_PULL_REQUEST == "false" &&
-    test $TRAVIS_BRANCH == "master" &&
-    test $TARGET == "x86_64-unknown-linux-gnu" &&
-    test $TRAVIS_RUST_VERSION = "stable" &&
+  - test "$TRAVIS_PULL_REQUEST" == "false" &&
+    test "$TRAVIS_BRANCH" == "master" &&
+    test "$TARGET" == "x86_64-unknown-linux-gnu" &&
+    test "$CHANNEL" = "stable" &&
     npm install stylus nib &&
     bash deploy.sh
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "mdbook"
-version = "0.0.12"
+version = "0.0.15"
 authors = ["Mathieu David <[email protected]>"]
 description = "create books from markdown files (like Gitbook)"
 documentation = "http://azerupi.github.io/mdBook/index.html"
@@ -16,19 +16,22 @@ exclude = [
 
 [dependencies]
 clap = "2.2.1"
-handlebars = "0.16.0"
-rustc-serialize = "0.3.18"
-pulldown-cmark = "0.0.7"
+handlebars = { version = "0.20.0", features = ["serde_type"] }
+serde = "0.8.17"
+serde_json = "0.8.3"
+pulldown-cmark = "0.0.8"
+log = "0.3"
+env_logger = "0.3.4"
 
 # Watch feature
 notify = { version = "2.5.5", optional = true }
 time = { version = "0.1.34", optional = true }
 crossbeam = { version = "0.2.8", optional = true }
 
 # Serve feature
-iron = { version = "0.3", optional = true }
-staticfile = { version = "0.2", optional = true }
-ws = { version = "0.4.6", optional = true}
+iron = { version = "0.4", optional = true }
+staticfile = { version = "0.3", optional = true }
+ws = { version = "0.5.1", optional = true}
 
 
 # Tests

README.md

@@ -23,8 +23,8 @@
 
 mdBook is a utility to create modern online books from markdown files.
 
-**This project is still evolving.**
-For more information, check the issue tracker.
+**This project is still evolving.**  
+See [#90](https://github.com/azerupi/mdBook/issues/90)
 
 
 ## What does it look like?

book-example/src/SUMMARY.md

@@ -1,10 +1,13 @@
 # Summary
 
+[Introduction](misc/introduction.md)
+
 - [mdBook](README.md)
 - [Command Line Tool](cli/cli-tool.md)
     - [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***: 

book-example/src/format/config.md

@@ -15,9 +15,14 @@ Here is an example of what a ***book.json*** file might look like:
 
 #### Supported variables
 
-- **title:** title of the book
-- **author:** author of the book
-- **description:** description, which is added as meta in the html head of each page.
-- **dest:** path to the directory where you want your book to be rendered. If a relative path is given it will be relative to the parent directory of the source directory
+If relative paths are given, they will be relative to the book's root, i.e. the
+parent directory of the source directory.
+
+- **title:** The title of the book.
+- **author:** The author of the book.
+- **description:** The description, which is added as meta in the html head of each page.
+- **src:** The path to the book's source files (chapters in Markdown, SUMMARY.md, etc.). Defaults to `root/src`.
+- **dest:** The path to the directory where you want your book to be rendered. Defaults to `root/book`.
+- **theme_path:** The path to a custom theme directory. Defaults to `root/theme`.
 
 ***note:*** *the supported configurable parameters are scarce at the moment, but more will be added in the future*

book-example/src/format/mathjax.md

@@ -16,6 +16,6 @@ To indicate a block equation
 
 use
 
-```
+```bash
 \\[ \mu = \frac{1}{N} \sum_{i=0} x_i \\]
 ```

book-example/src/format/rust.md

@@ -5,23 +5,23 @@
 There is a feature in mdBook that let's you hide code lines by prepending them with a `#`.
 
 ```bash
-#fn main() {
+# fn main() {
     let x = 5;
     let y = 6;
 
     println!("{}", x + y);
-#}
+# }
 ```
 
 Will render as
 
 ```rust
-#fn main() {
+# fn main() {
     let x = 5;
     let y = 7;
 
     println!("{}", x + y);
-#}
+# }
 ```
 
 

book-example/src/format/summary.md

@@ -27,6 +27,6 @@ allow for easy parsing. Let's see how you should format your `SUMMARY.md` file.
    ```
    You can either use `-` or `*` to indicate a numbered chapter.
 
-4. ***Sufix Chapter*** After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.
+4. ***Suffix Chapter*** After the numbered chapters you can add a couple of non-numbered chapters. They are the same as prefix chapters but come after the numbered chapters instead of before.
 
 All other elements are unsupported and will be ignored at best or result in an error.

book-example/src/format/theme/syntax-highlighting.md

@@ -28,23 +28,23 @@ There is a feature in mdBook that let's you hide code lines by prepending them w
 
 
 ```bash
-#fn main() {
+# fn main() {
     let x = 5;
     let y = 6;
 
     println!("{}", x + y);
-#}
+# }
 ```
 
 Will render as
 
 ```rust
-#fn main() {
+# fn main() {
     let x = 5;
     let y = 7;
 
     println!("{}", x + y);
-#}
+# }
 ```
 
 **At the moment, this only works for code examples that are annotated with `rust`. Because it would collide with semantics of some programming languages. In the future, we want to make this configurable through the `book.json` so that everyone can benefit from it.**

book-example/src/misc/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+A frontmatter chapter.

deploy.sh

@@ -15,13 +15,13 @@ cargo doc
 
 echo -e "${CYAN}Running mdbook build${NC}"
 # Run mdbook to generate the book
-target/$TARGET/debug/mdbook build book-example/
+target/"$TARGET"/debug/mdbook build book-example/
 
 echo -e "${CYAN}Copying book to target/doc${NC}"
 # Copy files from rendered book to doc root
-cp -R book-example/book/* target/$TARGET/doc/
+cp -R book-example/book/* target/doc/
 
-cd target/$TARGET/doc
+cd target/doc
 
 echo -e "${CYAN}Initializing Git${NC}"
 git init

src/bin/mdbook.rs

@@ -2,6 +2,9 @@
 extern crate mdbook;
 #[macro_use]
 extern crate clap;
+#[macro_use]
+extern crate log;
+extern crate env_logger;
 
 // Dependencies for the Watch feature
 #[cfg(feature = "watch")]
@@ -38,6 +41,8 @@ use mdbook::MDBook;
 const NAME: &'static str = "mdbook";
 
 fn main() {
+    env_logger::init().unwrap();
+
     // Create a list of valid arguments and sub-commands
     let matches = App::new(NAME)
                     .about("Create a book in form of a static website from markdown files")
@@ -62,7 +67,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();
@@ -81,6 +88,7 @@ fn main() {
 
     if let Err(e) = res {
         writeln!(&mut io::stderr(), "An error occured:\n{}", e).ok();
+        ::std::process::exit(101);
     }
 }
 
@@ -189,13 +197,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 +217,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());
 

src/book/book.rs

@@ -8,38 +8,40 @@ use book::chapter::Chapter;
 pub struct Book {
     metadata: BookMetadata,
 
-    preface: Vec<Chapter>,
-    chapters: Vec<Chapter>,
-    appendix: Vec<Chapter>,
+    frontmatter: Vec<Chapter>,
+    mainmatter: Vec<Chapter>,
+    backmatter: Vec<Chapter>,
 }
 
 impl Book {
-    /// Creates a new book with the given title, chapters are added with the `add_chapter` method
+    /// Creates a new book with the given title, chapters are added with the
+    /// `add_frontmatter_chapter`, `add_mainmatter_chapter`,
+    /// `add_backmatter_chapter` methods
     pub fn new(title: &str) -> Self {
         Book {
             metadata: BookMetadata::new(title),
 
-            preface: Vec::new(),
-            chapters: Vec::new(),
-            appendix: Vec::new(),
+            frontmatter: Vec::new(),
+            mainmatter: Vec::new(),
+            backmatter: Vec::new(),
         }
     }
 
-    /// Adds a new chapter at the end of the book
-    pub fn add_chapter(&mut self, chapter: Chapter) -> &mut Self {
-        self.chapters.push(chapter);
+    /// Adds a new mainmatter chapter
+    pub fn add_mainmatter_chapter(&mut self, chapter: Chapter) -> &mut Self {
+        self.mainmatter.push(chapter);
         self
     }
 
-    /// Adds a new preface chapter to the book, the preface chapters are in the order they were added
-    pub fn add_preface_chapter(&mut self, chapter: Chapter) -> &mut Self {
-        self.preface.push(chapter);
+    /// Adds a new frontmatter chapter
+    pub fn add_frontmatter_chapter(&mut self, chapter: Chapter) -> &mut Self {
+        self.frontmatter.push(chapter);
         self
     }
 
-    /// Adds a new appendix chapter to the book, they are in de order they are added
-    pub fn add_appendix_chapter(&mut self, chapter: Chapter) -> &mut Self {
-        self.appendix.push(chapter);
+    /// Adds a new backmatter chapter
+    pub fn add_backmatter_chapter(&mut self, chapter: Chapter) -> &mut Self {
+        self.backmatter.push(chapter);
         self
     }
 
@@ -57,9 +59,9 @@ impl Book {
     pub fn get_chapter(&self, section: &[usize]) -> Option<&Chapter> {
         match section.len() {
             0 => None,
-            1 => self.chapters.get(section[0]),
+            1 => self.mainmatter.get(section[0]),
             _ => {
-                self.chapters
+                self.mainmatter
                     .get(section[0])
                     .and_then(|ch| ch.get_sub_chapter(&section[1..]))
             },