Create book from markdown files. Like Gitbook but implemented in Rust.
mdBook is a utility to create modern online books from Markdown files.
Here are the main commands you will want to run. For a more exhaustive explanation, check out the User Guide.
See the User Guide and the API docs for more information.
from https://github.com/rust-lang-nursery/mdBook
Linux / OS X | |
Windows | |
What does it look like?
The User Guide for mdBook has been written in Markdown and is using mdBook to generate the online book-like website you can read. The documentation uses the latest version on GitHub and showcases the available features.Installation
There are multiple ways to install mdBook.-
Binaries
Binaries are available for download here. Make sure to put the path to the binary into yourPATH
.
-
From Crates.io
This requires at least Rust 1.20 and Cargo to be installed. Once you have installed Rust, type the following in the terminal:
This will download and compile mdBook for you, the only thing left to do is to add the Cargo bin directory to yourcargo install mdbook
PATH
.
Note for automatic deployment
If you are using a script to do automatic deployments using Travis or another CI server, we recommend that you specify a semver version range for mdBook when you install it through your script!
This will constrain the server to install the latests non-breaking version of mdBook and will prevent your books from failing to build because we released a new version. For example:
cargo install mdbook --vers "^0.1.0"
-
From Git
The version published to crates.io will ever so slightly be behind the version hosted here on GitHub. If you need the latest version you can build the git version of mdBook yourself. Cargo makes this super easy!
Again, make sure to add the Cargo bin directory to yourcargo install --git https://github.com/rust-lang-nursery/mdBook.git mdbook
PATH
.
-
For Contributions
If you want to contribute to mdBook you will have to clone the repository on your local machine:
git clone https://github.com/rust-lang-nursery/mdBook.git
cd
intomdBook/
and run
The resulting binary can be found incargo build
mdBook/target/debug/
under the namemdBook
ormdBook.exe
.
Usage
mdBook will primarily be used as a command line tool, even though it exposes all its functionality as a Rust crate for integration in other projects.Here are the main commands you will want to run. For a more exhaustive explanation, check out the User Guide.
-
mdbook init
The init command will create a directory with the minimal boilerplate to start with.
book-test/ ├── book └── src ├── chapter_1.md └── SUMMARY.md
book
andsrc
are both directories.src
contains the markdown files that will be used to render the output to thebook
directory.
Please, take a look at the CLI docs for more information and some neat tricks.
-
mdbook build
This is the command you will run to render your book, it reads theSUMMARY.md
file to understand the structure of your book, takes the markdown files in the source directory as input and outputs static html pages that you can upload to a server.
-
mdbook watch
When you run this command, mdbook will watch your markdown files to rebuild the book on every change. This avoids having to come back to the terminal to typemdbook build
over and over again.
-
mdbook serve
Does the same thing asmdbook watch
but additionally serves the book athttp://localhost:3000
(port is changeable) and reloads the browser when a change occurs.
-
mdbook clean
Delete directory in which generated book is located.
As a library
Aside from the command line interface, this crate can also be used as a library. This means that you could integrate it in an existing project, like a web-app for example. Since the command line interface is just a wrapper around the library functionality, when you use this crate as a library you have full access to all the functionality of the command line interface with an easy to use API and more!See the User Guide and the API docs for more information.
from https://github.com/rust-lang-nursery/mdBook
No comments:
Post a Comment