Linux / OS X | |
Windows | |
What does it look like?
Installation
- BinariesBinaries are available for download here. Make sure to put the path to the binary into your
PATH
. - From Crates.ioThis requires at least Rust 1.34 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 yourPATH
.Note for automatic deploymentIf 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 latest 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 GitThe 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/rust-lang-nursery/mdBook.git mdbook
Again, make sure to add the Cargo bin directory to yourPATH
. - For ContributionsIf 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 runcargo build
The resulting binary can be found inmdBook/target/debug/
under the namemdBook
ormdBook.exe
.
Usage
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.
3rd Party Plugins
{{#include some_file.ext}}
with the contents of that file. Some existing preprocessors are:index
- a built-in preprocessor (enabled by default) which will transform allREADME.md
chapters toindex.md
sofoo/README.md
can be accessed via the urlfoo/
when published to a browserlinks
- a built-in preprocessor (enabled by default) for expanding the{{# playpen}}
and{{# include}}
helpers in a chapter.
html
- the built-in renderer which will generate a HTML version of the booklinkcheck
- a backend which will check that all links are validepub
- an experimental EPUB generator
Note for Developers: Feel free to send us a PR if you've developed your own plugin and want it mentioned here.
book.toml
file.$ cargo install mdbook-linkcheck
$ edit book.toml && cat book.toml
[book]
title = "My Awesome Book"
authors = ["Michael-F-Bryan"]
[output.html]
[output.linkcheck] # enable the "mdbook-linkcheck" renderer
$ mdbook build
2018-10-20 13:57:51 [INFO] (mdbook::book): Book building has started
2018-10-20 13:57:51 [INFO] (mdbook::book): Running the html backend
2018-10-20 13:57:53 [INFO] (mdbook::book): Running the linkcheck backend
As a library
https://github.com/rust-lang/mdBook
mdBook 是一个开源的静态站点生成器,用于创建基于 Markdown 的电子书和文档网站。它是为了方便作者使用简单的文本格式(Markdown)来编写和组织文档,然后将其转换为漂亮的 HTML 网页。
mdBook 使用 Rust 编写,它提供了一组命令行工具和库,用于处理 Markdown 文件并将其呈现为静态 HTML 网页。它的设计目标是提供简单易用的方式来创建文档,同时支持自定义主题和布局,以满足各种不同的需求。
----------------------------------------------
用mdbook记录笔记
mdbook
mdbook
是一个类似与 gitbook
的命令行工具,使用 Markdown 格式文件自动生成书籍文档,
而构建 mdbook
的语言是 rust
,其源码存放于 github,
而其自身文档就是 mdbook
自动生成的。
编译 mdbook
编译之前,系统中需要安装 rustc
和 cargo
,
rustc
是 rust 语言的编译器,
而 cargo
是用来管理 rust 源码下载、编译、构建的工具。
下载 mdbook
源码:
git clone --depth=1 https://github.com/azerupi/mdBook.git
编译源码:
cd mdBook
cargo build --release
此时可执行文件 mdbook
就会出现在 ./target/release
文件夹下,
应将此文件夹放入环境变量 PATH
内。
运行 mdbook
init 子命令
运行 init
子命令如下:
cd book-test
mdbook init
也可以初始化指定文件夹:
mdbook init /path/to/book-test
这样 mdbook
会自动生成一个如下的目录结构:
book-test/
├── book
└── src
├── chapter_1.md
└── SUMMARY.md
其中 src
文件夹就是用来存放 markdown 格式文档,
book
文件夹就是用来存放自动生成的文档,
SUMMARY.md
文件是一个最重要的文件,它是用来定义书籍文档的框架结构的,用来建立书籍文档的索引及其链接文件。
build 子命令
build
子命令就是用来渲染书籍文档的:
cd book-test
mdbook build
也可以渲染指定文件夹:
mdbook build /path/to/book-test
这样,mdbook
就会解析 SUMMARY.md
文件,来了解书籍文档的框架,获取链接文件,渲染相应 markdown 文件。
SUMMARY.md 格式
允许元素:
-
Title
:通常是# Summary
这种形式,它只是用来代表一个标题,解析时mdbook
命令会忽略该行 -
list link
:列表元素,用来构建书籍文档的框架结构,形式如下:- [Title of the Chapter](relative/path/to/markdown.md)
示例如下:
# Summary
- [mdBook](README.md)
- [Command Line Tool](cli/cli-tool.md)
- [init](cli/init.md)
- [build](cli/build.md)
- [Format](format/format.md)
- [SUMMARY.md](format/summary.md)
- [Configuration](format/config.md)
- [Theme](format/theme/theme.md)
- [index.hbs](format/theme/index-hbs.md)
- [Syntax highlighting](format/theme/syntax-highlighting.md)
- [Rust Library](lib/lib.md)
-----------------------------------
https://github.com/BITcyman/cyman-mdblog