131 lines
4.8 KiB
Markdown
131 lines
4.8 KiB
Markdown
<div align="center">
|
|
|
|
<h1>PageTop mdBook</h1>
|
|
|
|
<p>Extension for <strong>PageTop</strong> that embeds books generated by <a href="https://rust-lang.github.io/mdBook/">mdBook</a> into PageTop applications.</p>
|
|
|
|
[](https://docs.rs/pagetop-mdbook)
|
|
[](https://crates.io/crates/pagetop-mdbook)
|
|
[](https://crates.io/crates/pagetop-mdbook)
|
|
[](https://git.cillero.es/manuelcillero/pagetop-mdbook#license)
|
|
|
|
</div>
|
|
|
|
## 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<ExtensionRef> {
|
|
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.
|