PageTop mdBook

Extension for PageTop that embeds books generated by mdBook into PageTop applications.

[![Doc API](https://img.shields.io/docsrs/pagetop-mdbook?label=Doc%20API&style=for-the-badge&logo=Docs.rs)](https://docs.rs/pagetop-mdbook) [![Crates.io](https://img.shields.io/crates/v/pagetop-mdbook.svg?style=for-the-badge&logo=ipfs)](https://crates.io/crates/pagetop-mdbook) [![Downloads](https://img.shields.io/crates/d/pagetop-mdbook.svg?label=Downloads&style=for-the-badge&logo=transmission)](https://crates.io/crates/pagetop-mdbook) [![License](https://img.shields.io/badge/license-MIT%2FApache-blue.svg?label=License&style=for-the-badge)](https://git.cillero.es/manuelcillero/pagetop-mdbook#license)
## About PageTop [PageTop](https://docs.rs/pagetop) is a development environment that reclaims the essence of the classic web to build modular, extensible and configurable SSR (*server-side rendered*) web solutions, based on HTML, CSS and JavaScript. ## Overview Books are built with mdBook when the application is compiled, embedded into the binary, and served as regular PageTop pages: each chapter is rendered inside the active theme, with the page title and language taken from the book. It is useful for product or API documentation, tutorials, course material or any content that needs a navigable presentation. Three pieces work together: - The `build` module, used from the application's `build.rs`, runs `mdbook build` on every book and bundles the result. - The `MdBook` extension serves the resources shared by every book (styles, fonts and scripts) under `/mdbook`. - The `serve_mdbook!` macro publishes a bundle of books under a route of the application. ## Quick guide **Add the dependencies** to the `Cargo.toml` of the application. The crate is needed both at run time and in `build.rs`; `pagetop` must be a direct dependency, because the bundle generated in `build.rs` refers to it: ```toml [dependencies] pagetop = { ... } pagetop-mdbook = { ... } [build-dependencies] pagetop-mdbook = { ... } ``` **Write the books** under `doc/` (at the level of `src/`), one directory with a `book.toml` file per book, and organize them as you wish. For example, by version and language: ```text doc/ ├── theme/ <- copy of template/theme from this repository └── v1.0/ ├── en/ <- book.toml, src/SUMMARY.md... └── es/ ``` Every book must use the theme in the `template/theme` directory of this repository, which marks where the content of each chapter starts and exposes its title and language to PageTop. See `template/book.toml`: ```toml [output.html] theme = "../../theme" ``` **Build and bundle the books** in `build.rs`. Only the books that changed since the last build are built again, into `static/doc/` (it needs the `mdbook` command on the `PATH`): ```rust,no_run use pagetop_mdbook::build::{MdBookOptions, mdbooks_and_bundle}; fn main() -> std::io::Result<()> { mdbooks_and_bundle(MdBookOptions::new()) } ``` **Declare the extension and publish the books** under a route of the application: ```rust,ignore use pagetop::prelude::*; struct MyApp; #[async_trait] impl Extension for MyApp { fn dependencies(&self) -> Vec { vec![&pagetop_mdbook::MdBook] } fn configure_router(&self, router: Router) -> Router { pagetop_mdbook::serve_mdbook!(router, [doc] => "/doc"); router } } ``` With the layout above, the English book is available at `/doc/v1.0/en/index.html`. The resources common to every book are served by the extension under `/mdbook`, so they are left out of the application's bundle. ## Credits The `static` directory includes the common resources of the mdBook HTML renderer: mdBook styles ([MPL-2.0](https://github.com/rust-lang/mdBook/blob/master/LICENSE)), [Font Awesome 4.7](https://fontawesome.com/v4/license/) (SIL OFL 1.1 for the font, MIT for the CSS), and the [Open Sans](https://fonts.google.com/specimen/Open+Sans) (Apache-2.0) and [Source Code Pro](https://github.com/adobe-fonts/source-code-pro) (SIL OFL 1.1) fonts, whose license files are included. The `template/theme` directory is adapted from the default mdBook theme. ## Warning **PageTop** is a personal project to learn [Rust](https://www.rust-lang.org/) and its ecosystem. Its API is subject to frequent changes. Production use is not recommended, at least until version **1.0.0** is released. ## License The code is available under a dual license: * **MIT License** ([LICENSE-MIT](LICENSE-MIT) or https://opensource.org/licenses/MIT) * **Apache License, Version 2.0** ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0) You may choose either license. This dual-license approach is the de facto standard in the Rust ecosystem.