用rust实现的静态电子书网站程序-mdBook

Linux / OS X
Windows

mdBook is a utility to create modern online books from Markdown files.

What does it look like?

The Documentation 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.

1. Binaries
   Binaries are available for download here. Make sure to put the path to the binary into your PATH.
   
2. From Crates.io
   This requires Rust and Cargo to be installed. Once you have installed Rust, type the following in the terminal:
   

   cargo install mdbook
   

   This will download and compile mdBook for you, the only thing left to do is to add the Cargo bin directory to your 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"
   

3. 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!
   

   cargo install --git https://github.com/azerupi/mdBook.git
   

   Again, make sure to add the Cargo bin directory to your PATH.
   
4. 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/azerupi/mdBook.git
   

   cd into mdBook/ and run
   

   cargo build
   

   The resulting binary can be found in mdBook/target/debug/ under the name mdBook or mdBook.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 documentation.

• 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 and src are both directories. src contains the markdown files that will be used to render the output to the book directory.
  Please, take a look at the Documentation for more information and some neat tricks.
  
• mdbook build
  This is the command you will run to render your book, it reads the SUMMARY.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 type mdbook build over and over again.
  
• mdbook serve
  Does the same thing as mdbook watch but additionally serves the book at http://localhost:3000 (port is changeable) and reloads the browser when a change occurs.
  

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 Documentation and the API docs for more information.

from https://github.com/azerupi/mdBook
--------

示例：https://doc.rust-lang.org/book/
The second edition is a rewrite that will be printed by NoStarch Press, available around October 2017.
You can read it online; the last few chapters aren't completed yet, but the first half of the book is much improved from the first edition. We recommend starting with the second edition.
The first edition is still available to read online.

Requirements

Building the book requires mdBook >= v0.0.13. To get it:

$ cargo install mdbook

Building

To build the book, first cd into either the first-edition or second-edition directory depending on which edition of the book you would like to build. Then type:

$ mdbook build

The output will be in the book subdirectory. To check it out, open it in your web browser.
Firefox:

$ firefox book/index.html                       # Linux
$ open -a "Firefox" book/index.html             # OS X
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
$ start firefox.exe .\book\index.html           # Windows (Cmd)

Chrome:

$ google-chrome book/index.html                 # Linux
$ open -a "Google Chrome" book/index.html       # OS X
$ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
$ start chrome.exe .\book\index.html            # Windows (Cmd)

To run the tests:

$ mdbook test

Contributing

We'd love your help! Please see CONTRIBUTING.md to learn about the kinds of contributions we're looking for.

Translations

We'd especially love help translating the second edition of the book! See the Translations label to join in efforts that are currently in progress. Open a new issue to start working on a new language! We're waiting on mdbook support for multiple languages before we merge any in, but feel free to start! The chapters in the frozen column of the project won't see major changes, so if you start with those, you won't have to redo work :)

No Starch

As the second edition of the book will be published by No Starch, we first iterate here, then ship the text off to No Starch. Then they do editing, and we fold it back in.
As such, there’s a directory, nostarch, which corresponds to the text in No Starch’s system.
When we've started working with No Starch in a word doc, we will also check those into the repo in the nostarch/odt directory. To extract the text from the word doc as markdown in order to backport changes to the online book:

1. Open the doc file in LibreOffice
2. Accept all tracked changes
3. Save as Microsoft Word 2007-2013 XML (.docx) in the tmp directory
4. Run ./doc-to-md.sh
5. Inspect changes made to the markdown file in the nostarch directory and copy the changes to the src directory as appropriate.

Graphviz dot

This is mostly for Carol's reference because she keeps having to look it up.
We're using Graphviz for some of the diagrams in the book. The source for those files live in the dot directory. To turn a dot file, for example, dot/trpl04-01.dot into an svg, run:

$ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg

In the generated SVG, remove the width and the height attributes from the svg element and set the viewBox attribute to 0.00 0.00 1000.00 1000.00 or other values that don't cut off the image.

Spellchecking

To scan source files for spelling errors, you can use the spellcheck.sh script. It needs a dictionary of valid words, which is provided in dictionary.txt. If the script produces a false positive (say, you used word BTreeMap which the script considers invalid), you need to add this word to dictionary.txt (keep the sorted order for consistency).

from https://github.com/rust-lang/book