4.8 KiB
PageTop mdBook
Extension for PageTop that embeds books generated by mdBook into PageTop applications.
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
buildmodule, used from the application'sbuild.rs, runsmdbook buildon every book and bundles the result. - The
MdBookextension 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:
-
MIT License (LICENSE-MIT or https://opensource.org/licenses/MIT)
-
Apache License, Version 2.0 (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.