2021-07-25 09:41:53 +08:00
|
|
|
# Introduction
|
2015-07-30 17:59:08 +08:00
|
|
|
|
2021-07-25 09:41:53 +08:00
|
|
|
**mdBook** is a command line tool and Rust crate to create books with Markdown. The output resembles tools like Gitbook,
|
|
|
|
|
and is ideal for creating product or API documentation, tutorials, course materials or anything that requires a clean,
|
|
|
|
|
easily navigable and customizable presentation. mdBook is written in [Rust](https://www.rust-lang.org); its performance
|
|
|
|
|
and simplicity made it ideal for use as a tool to publish directly to hosted websites such
|
2021-07-25 12:17:41 +08:00
|
|
|
as [GitHub Pages](https://pages.github.com) via automation. This guide, in fact, serves as both the mdBook documentation
|
2021-07-25 09:41:53 +08:00
|
|
|
and a fine example of what mdBook produces.
|
2015-07-30 17:59:08 +08:00
|
|
|
|
2021-07-25 09:41:53 +08:00
|
|
|
mdBook includes built in support for both preprocessing your Markdown and alternative renderers for producing formats
|
2021-07-25 12:17:41 +08:00
|
|
|
other than HTML. These facilities also enable other functionality such as
|
2021-07-25 09:41:53 +08:00
|
|
|
validation. [Searching](https://crates.io/search?q=mdbook&sort=relevance) Rust's [crates.io](https://crates.io) is a
|
|
|
|
|
great way to discover more extensions.
|
2015-07-30 17:59:08 +08:00
|
|
|
|
2021-07-25 09:41:53 +08:00
|
|
|
## API Documentation
|
2015-07-30 17:59:08 +08:00
|
|
|
|
2021-07-25 09:41:53 +08:00
|
|
|
In addition to the above features, mdBook also has a Rust [API](https://docs.rs/mdbook/*/mdbook/). This allows you to
|
|
|
|
|
write your own preprocessor or renderer, as well as incorporate mdBook features into other applications.
|
|
|
|
|
The [For Developers](for_developers) section of this guide contains more information and some examples.
|
2015-08-06 21:24:34 +08:00
|
|
|
|
2021-07-25 09:41:53 +08:00
|
|
|
## Markdown
|
|
|
|
|
|
|
|
|
|
mdBook's [parser](https://github.com/raphlinus/pulldown-cmark) adheres to the [CommonMark](https://commonmark.org/)
|
|
|
|
|
specification. You can take a quick [tutorial](https://commonmark.org/help/tutorial/),
|
|
|
|
|
or [try out](https://spec.commonmark.org/dingus/) CommonMark in real time. For a more in-depth experience, check out the
|
|
|
|
|
[Markdown Guide](https://www.markdownguide.org).
|
|
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
|
|
mdBook is free and open source. You can find the source code on
|
|
|
|
|
[GitHub](https://github.com/rust-lang/mdBook) and issues and feature requests can be posted on
|
|
|
|
|
the [GitHub issue tracker](https://github.com/rust-lang/mdBook/issues). mdBook relies on the community to fix bugs and
|
|
|
|
|
add features: if you'd like to contribute, please read
|
|
|
|
|
the [CONTRIBUTING](https://github.com/rust-lang/mdBook/blob/master/CONTRIBUTING.md) guide and consider opening
|
|
|
|
|
a [pull request](https://github.com/rust-lang/mdBook/pulls).
|
2015-08-06 21:24:34 +08:00
|
|
|
|
2015-07-30 17:59:08 +08:00
|
|
|
## License
|
|
|
|
|
|
2021-07-25 12:17:41 +08:00
|
|
|
The mdBook source and documentation are released under
|
2021-07-25 09:41:53 +08:00
|
|
|
the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/).
|
