From b85d5eb455889d52c70ea984be1d155126932a19 Mon Sep 17 00:00:00 2001 From: josh rotenberg Date: Sat, 24 Jul 2021 18:41:53 -0700 Subject: [PATCH 1/2] updates to the mdbook introduction --- guide/src/README.md | 49 +++++++++++++++++++++++++++++--------------- guide/src/SUMMARY.md | 2 +- 2 files changed, 33 insertions(+), 18 deletions(-) diff --git a/guide/src/README.md b/guide/src/README.md index 99e55bce..82932ef7 100644 --- a/guide/src/README.md +++ b/guide/src/README.md @@ -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 documenation +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 facilites 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 is released under +the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/). diff --git a/guide/src/SUMMARY.md b/guide/src/SUMMARY.md index d95410cc..37e9fca0 100644 --- a/guide/src/SUMMARY.md +++ b/guide/src/SUMMARY.md @@ -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) From 49b75810faa702af57b74a7bd9c51e0d4271975a Mon Sep 17 00:00:00 2001 From: josh rotenberg Date: Sat, 24 Jul 2021 21:17:41 -0700 Subject: [PATCH 2/2] fix a few typos --- guide/src/README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guide/src/README.md b/guide/src/README.md index 82932ef7..ac6f48e7 100644 --- a/guide/src/README.md +++ b/guide/src/README.md @@ -4,11 +4,11 @@ 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 documenation +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. mdBook includes built in support for both preprocessing your Markdown and alternative renderers for producing formats -other than HTML. These facilites also enable other functionality such as +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. @@ -36,5 +36,5 @@ a [pull request](https://github.com/rust-lang/mdBook/pulls). ## License -The mdBook source and documentation is released under +The mdBook source and documentation are released under the [Mozilla Public License v2.0](https://www.mozilla.org/MPL/2.0/).