PageTop extension that embeds books generated by mdBook into PageTop applications.
Find a file
Manuel Cillero 2bd99b156e 🎉 Initial commit
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-17 08:03:22 +02:00
src 🎉 Initial commit 2026-10-17 08:03:22 +02:00
static 🎉 Initial commit 2026-10-17 08:03:22 +02:00
template 🎉 Initial commit 2026-10-17 08:03:22 +02:00
.gitignore 🎉 Initial commit 2026-10-17 08:03:22 +02:00
build.rs 🎉 Initial commit 2026-10-17 08:03:22 +02:00
Cargo.lock 🎉 Initial commit 2026-10-17 08:03:22 +02:00
Cargo.toml 🎉 Initial commit 2026-10-17 08:03:22 +02:00
LICENSE-APACHE 🎉 Initial commit 2026-10-17 08:03:22 +02:00
LICENSE-MIT 🎉 Initial commit 2026-10-17 08:03:22 +02:00
README.md 🎉 Initial commit 2026-10-17 08:03:22 +02:00
rustfmt.toml 🎉 Initial commit 2026-10-17 08:03:22 +02:00

PageTop mdBook

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

Doc API Crates.io Downloads License

About PageTop

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:

[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:

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:

[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):

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:

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), Font Awesome 4.7 (SIL OFL 1.1 for the font, MIT for the CSS), and the Open Sans (Apache-2.0) and 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 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:

You may choose either license. This dual-license approach is the de facto standard in the Rust ecosystem.