Merge pull request #1609 from joshrotenberg/intro_updates
Updates to the mdbook introduction
This commit is contained in:
commit
2ccfaadd1d
|
@ -1,25 +1,40 @@
|
|||
# mdBook
|
||||
# Introduction
|
||||
|
||||
**mdBook** is a command line tool and Rust crate to create books using Markdown
|
||||
(as by the [CommonMark](https://commonmark.org/) specification) files. It's very
|
||||
similar to Gitbook but written in [Rust](http://www.rust-lang.org).
|
||||
**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
|
||||
as [GitHub Pages](https://pages.github.com) via automation. This guide, in fact, serves as both the mdBook documentation
|
||||
and a fine example of what mdBook produces.
|
||||
|
||||
What you are reading serves as an example of the output of mdBook and at the
|
||||
same time as a high-level documentation.
|
||||
mdBook includes built in support for both preprocessing your Markdown and alternative renderers for producing formats
|
||||
other than HTML. These facilities also enable other functionality such as
|
||||
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.
|
||||
|
||||
mdBook is free and open source, you can find the source code on
|
||||
[GitHub](https://github.com/rust-lang/mdBook). Issues and feature
|
||||
requests can be posted on the [GitHub issue
|
||||
tracker](https://github.com/rust-lang/mdBook/issues).
|
||||
## API Documentation
|
||||
|
||||
## API docs
|
||||
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.
|
||||
|
||||
Alongside this book you can also read the [API
|
||||
docs](https://docs.rs/mdbook/*/mdbook/) generated by Rustdoc if you would like
|
||||
to use mdBook as a crate or write a new renderer and need a more low-level
|
||||
overview.
|
||||
## 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).
|
||||
|
||||
## License
|
||||
|
||||
mdBook, all the source code, is released under the [Mozilla Public License
|
||||
v2.0](https://www.mozilla.org/MPL/2.0/).
|
||||
The mdBook source and documentation are released under
|
||||
the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/).
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# Summary
|
||||
|
||||
- [mdBook](README.md)
|
||||
- [Introduction](README.md)
|
||||
- [Command Line Tool](cli/README.md)
|
||||
- [init](cli/init.md)
|
||||
- [build](cli/build.md)
|
||||
|
|
Loading…
Reference in New Issue