The hub for mdbook.
mdbook-hub is a decentralized book hosting platform for books generated by mdbook. If mdbook is the librustdoc, then mdbook-hub is the docs.rs.
mdbook-hub aimed to bring the best publishing, and hosting experience to mdbook users. Imagine, we run mdbook publish in the directory of The Rust Programming Language Book, we can publish the book with the unique url https://mdbook.org/rust-lang/book effortlessly, no Github Pages setup required, no CI required.
The mdbook publish is similar to cargo publish which can publish our crate to crates.io and get a unique url on docs.rs.
mdbook has no
publishsubcommand yet, we need to add it.
mdbook-hub mainly has two concepts:
- User
- Book
The user is the organization or individual who owns the book (the author of the book). Every user has a unique handle, such as rust-lang (organization), folyd(individual). The https://mdbook.org/{handle} is the profile page to list all of public books of this user. For example, we can visit https://mdbook.org/rust-lang to view all books from Rust official.
Just an ordinary book generated by mdbook. However, the book must have at least one author. If a user is the author or co-author of a book, the user profile page can display this book.
Every published book has its unique url. For instance, the https://mdbook.org/rust-lang/book is the book whose id is book owned by rust-lang user.
Yes, this is like the relationship between a GitHub user and a GitHub repository. So, you can get why we call mdbook-hub.
Technically, mdbook-hub is very similar to the combination of crates.io and docs.rs, except it is for books. We use mdbook to automatically generate HTML pages once a user publishes a new version of his book. The generated static book will be uploaded to AWS S3 or other similar static hosting platforms.
mdbook-hub has several critical components:
- Server
mdbooksubcommand
mdbook-hub is a web server used to handle API requests such as but not limited to user authentication and book publishing.
We need to add two subcommands to mdbook:
-
mdbook login- Authenticate a user with an API token generated frommdbook-hubserver. -
mdbook publish- Publish the book tomdbook-hubif the user is authenticated.
A mdbook-hub cargo subcommand is another good choice if we cannot add above two subcommands to mdbook.
$ cargo install mdbook-hub
$ cargo mdbook login # alternative to `mdbook login`
$ cargo mdbook publish # alternative to `mdbook publish`- Support login with API token
- Support publish book
- Support book i18n
- Book page view statistics