https://github.com/folyd/mdbook-hub
The hub for mdbook
https://github.com/folyd/mdbook-hub
mdbook rust
Last synced: 10 months ago
JSON representation
The hub for mdbook
- Host: GitHub
- URL: https://github.com/folyd/mdbook-hub
- Owner: Folyd
- License: mit
- Created: 2022-10-19T05:34:41.000Z (over 3 years ago)
- Default Branch: master
- Last Pushed: 2022-10-25T16:40:04.000Z (over 3 years ago)
- Last Synced: 2025-07-29T23:51:04.140Z (11 months ago)
- Topics: mdbook, rust
- Language: Rust
- Homepage: https://mdbook.org
- Size: 5.86 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mdbook-hub
The hub for mdbook.
## What is mdbook-hub?
`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`.
## Why mdbook-hub?
`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](https://crates.io) and get a unique url on [docs.rs](https://docs.rs).
> mdbook has no `publish` subcommand yet, we need to add it.
## How mdbook-hub works?
`mdbook-hub` mainly has two concepts:
- User
- Book
### User
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.
### Book
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**.
## Technical design
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
- `mdbook` subcommand
### Server
`mdbook-hub` is a web server used to handle API requests such as but not limited to user authentication and book publishing.
### Subcommand
We need to add two subcommands to `mdbook`:
- `mdbook login` - Authenticate a user with an API token generated from `mdbook-hub` server.
- `mdbook publish` - Publish the book to `mdbook-hub` if the user is authenticated.
### Alternative
A `mdbook-hub` cargo subcommand is another good choice if we cannot add above two subcommands to `mdbook`.
```sh
$ cargo install mdbook-hub
$ cargo mdbook login # alternative to `mdbook login`
$ cargo mdbook publish # alternative to `mdbook publish`
```
## Roadmap
- Support login with API token
- Support publish book
- Support book i18n
- Book page view statistics