🎉 Initial commit
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
2bd99b156e
48 changed files with 9069 additions and 0 deletions
131
README.md
Normal file
131
README.md
Normal 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>
|
||||
|
||||
[](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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue