src/vendor/mdbook/README.md

   1 # mdBook
   2
   3 <table>
   4     <tr>
   5         <td><strong>Linux / OS X</strong></td>
   6         <td>
   7             <a href="https://travis-ci.org/rust-lang-nursery/mdBook"><img src="https://travis-ci.org/rust-lang-nursery/mdBook.svg?branch=master"></a>
   8         </td>
   9     </tr>
  10     <tr>
  11         <td><strong>Windows</strong></td>
  12         <td>
  13             <a href="https://ci.appveyor.com/project/azerupi/mdbook/"><img src="https://ci.appveyor.com/api/projects/status/o38racsnbcospyc8/branch/master?svg=true"></a>
  14         </td>
  15     </tr>
  16     <tr>
  17         <td colspan="2">
  18             <a href="https://crates.io/crates/mdbook"><img src="https://img.shields.io/crates/v/mdbook.svg"></a>
  19             <a href="LICENSE"><img src="https://img.shields.io/github/license/rust-lang-nursery/mdBook.svg"></a>
  20         </td>
  21     </tr>
  22 </table>
  23
  24 mdBook is a utility to create modern online books from Markdown files.
  25
  26
  27 ## What does it look like?
  28
  29 The [User Guide] for mdBook has been written in Markdown and is using mdBook to
  30 generate the online book-like website you can read. The documentation uses the
  31 latest version on GitHub and showcases the available features.
  32
  33 ## Installation
  34
  35 There are multiple ways to install mdBook.
  36
  37 1. **Binaries**
  38
  39    Binaries are available for download [here][releases]. Make sure to put the
  40    path to the binary into your `PATH`.
  41
  42 2. **From Crates.io**
  43 j
  44    This requires [Rust] and Cargo to be installed. Once you have installed
  45    Rust, type the following in the terminal:
  46
  47    ```
  48    cargo install mdbook
  49    ```
  50
  51    This will download and compile mdBook for you, the only thing left to do is
  52    to add the Cargo bin directory to your `PATH`.
  53
  54    **Note for automatic deployment**
  55
  56    If you are using a script to do automatic deployments using Travis or
  57    another CI server, we recommend that you specify a semver version range for
  58    mdBook when you install it through your script!
  59
  60    This will constrain the server to install the latests **non-breaking**
  61    version of mdBook and will prevent your books from failing to build because
  62    we released a new version. For example:
  63
  64    ```
  65    cargo install mdbook --vers "^0.1.0"
  66    ```
  67
  68 3. **From Git**
  69
  70    The version published to crates.io will ever so slightly be behind the
  71    version hosted here on GitHub. If you need the latest version you can build
  72    the git version of mdBook yourself. Cargo makes this ***super easy***!
  73
  74    ```
  75    cargo install --git https://github.com/rust-lang-nursery/mdBook.git mdbook
  76    ```
  77
  78    Again, make sure to add the Cargo bin directory to your `PATH`.
  79
  80 4. **For Contributions**
  81
  82    If you want to contribute to mdBook you will have to clone the repository on
  83    your local machine:
  84
  85    ```
  86    git clone https://github.com/rust-lang-nursery/mdBook.git
  87    ```
  88
  89    `cd` into `mdBook/` and run
  90
  91    ```
  92    cargo build
  93    ```
  94
  95    The resulting binary can be found in `mdBook/target/debug/` under the name
  96    `mdBook` or `mdBook.exe`.
  97
  98
  99 ## Usage
 100
 101 mdBook will primarily be used as a command line tool, even though it exposes
 102 all its functionality as a Rust crate for integration in other projects.
 103
 104 Here are the main commands you will want to run. For a more exhaustive
 105 explanation, check out the [User Guide].
 106
 107 - `mdbook init`
 108
 109     The init command will create a directory with the minimal boilerplate to
 110     start with.
 111
 112     ```
 113     book-test/
 114     ├── book
 115     └── src
 116         ├── chapter_1.md
 117         └── SUMMARY.md
 118     ```
 119
 120     `book` and `src` are both directories. `src` contains the markdown files
 121     that will be used to render the output to the `book` directory.
 122
 123     Please, take a look at the [CLI docs] for more information and some neat tricks.
 124
 125 - `mdbook build`
 126
 127     This is the command you will run to render your book, it reads the
 128     `SUMMARY.md` file to understand the structure of your book, takes the
 129     markdown files in the source directory as input and outputs static html
 130     pages that you can upload to a server.
 131
 132 - `mdbook watch`
 133
 134     When you run this command, mdbook will watch your markdown files to rebuild
 135     the book on every change. This avoids having to come back to the terminal
 136     to type `mdbook build` over and over again.
 137
 138 - `mdbook serve`
 139
 140     Does the same thing as `mdbook watch` but additionally serves the book at
 141     `http://localhost:3000` (port is changeable) and reloads the browser when a
 142     change occurs.
 143
 144
 145 ### As a library
 146
 147 Aside from the command line interface, this crate can also be used as a
 148 library. This means that you could integrate it in an existing project, like a
 149 web-app for example. Since the command line interface is just a wrapper around
 150 the library functionality, when you use this crate as a library you have full
 151 access to all the functionality of the command line interface with an easy to
 152 use API and more!
 153
 154 See the [User Guide] and the [API docs] for more information.
 155
 156 ## Contributions
 157
 158 Contributions are highly appreciated and encouraged! Don't hesitate to
 159 participate to discussions in the issues, propose new features and ask for
 160 help.
 161
 162 If you are just starting out with Rust, there are a series of issus that are
 163 tagged [E-Easy] and **we will gladly mentor you** so that you can successfully
 164 go through the process of fixing a bug or adding a new feature! Let us know if
 165 you need any help.
 166
 167 For more info about contributing, check out our [contribution guide] who helps
 168 you go through the build and contribution process!
 169
 170 There is also a [rendered version][master-docs] of the latest API docs
 171 available, for those hacking on `master`.
 172
 173
 174 ## License
 175
 176 All the code in this repository is released under the ***Mozilla Public License v2.0***, for more information take a look at the [LICENSE] file.
 177
 178
 179 [User Guide]: https://rust-lang-nursery.github.io/mdBook/
 180 [API docs]: https://docs.rs/mdbook/*/mdbook/
 181 [E-Easy]: https://github.com/rust-lang-nursery/mdBook/issues?q=is%3Aopen+is%3Aissue+label%3AE-Easy
 182 [contribution guide]: https://github.com/rust-lang-nursery/mdBook/blob/master/CONTRIBUTING.md
 183 [LICENSE]: https://github.com/rust-lang-nursery/mdBook/blob/master/LICENSE
 184 [releases]: https://github.com/rust-lang-nursery/mdBook/releases
 185 [Rust]: https://www.rust-lang.org/
 186 [CLI docs]: http://rust-lang-nursery.github.io/mdBook/cli/init.html
 187 [master-docs]: http://rust-lang-nursery.github.io/mdBook/mdbook/