🎉 Initial commit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Manuel Cillero 2026-10-17 08:03:22 +02:00
commit 2bd99b156e
48 changed files with 9069 additions and 0 deletions

131
README.md Normal file
View file

@ -0,0 +1,131 @@
<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>
[![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)
</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.