🎉 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

10
.gitignore vendored Normal file
View file

@ -0,0 +1,10 @@
# Build directories
**/target
# Log files
**/log/*.log*
# Local configuration files
**/local.*.toml
**/local.toml
.env

2377
Cargo.lock generated Normal file

File diff suppressed because it is too large Load diff

20
Cargo.toml Normal file
View file

@ -0,0 +1,20 @@
[package]
name = "pagetop-mdbook"
version = "0.0.1"
edition = "2024"
rust-version = "1.88"
description = "PageTop extension that embeds books generated by mdBook into PageTop applications."
categories = ["web-programming"]
keywords = ["pagetop", "mdbook", "book", "markdown", "documentation"]
exclude = ["/template"]
repository = "https://git.cillero.es/manuelcillero/pagetop-mdbook"
homepage = "https://pagetop.cillero.es"
license = "MIT OR Apache-2.0"
authors = ["Manuel Cillero <manuel@cillero.es>"]
[dependencies]
pagetop = { path = "../pagetop" }
pagetop-build = { path = "../pagetop/helpers/pagetop-build" }
[build-dependencies]
pagetop-build = { path = "../pagetop/helpers/pagetop-build" }

201
LICENSE-APACHE Normal file
View file

@ -0,0 +1,201 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright 2022 Manuel Cillero
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

21
LICENSE-MIT Normal file
View file

@ -0,0 +1,21 @@
MIT License
Copyright (c) 2022 Manuel Cillero
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

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.

7
build.rs Normal file
View file

@ -0,0 +1,7 @@
use pagetop_build::StaticFilesBundle;
fn main() -> std::io::Result<()> {
StaticFilesBundle::from_dir("./static", None)
.with_name("mdbook")
.build()
}

1
rustfmt.toml Normal file
View file

@ -0,0 +1 @@
edition = "2024"

107
src/build.rs Normal file
View file

@ -0,0 +1,107 @@
//! Builds the mdBook books of an application and bundles them, from its `build.rs`.
//!
//! [`mdbooks_and_bundle()`] looks for books under a directory, runs `mdbook build` on those that
//! changed since the last build, and bundles the generated files so that
//! [`serve_mdbook!`](crate::serve_mdbook) can publish them:
//!
//! ```rust,no_run
//! // build.rs
//! use pagetop_mdbook::build::{MdBookOptions, mdbooks_and_bundle};
//!
//! fn main() -> std::io::Result<()> {
//! mdbooks_and_bundle(MdBookOptions::new())
//! }
//! ```
//!
//! It needs the `mdbook` command on the `PATH`. If the books are already built (for example, in an
//! environment without mdBook), [`bundle_only()`] just bundles the existing files.
use pagetop_build::StaticFilesBundle;
use std::fs;
use std::io;
use std::path::Path;
use std::time::{SystemTime, UNIX_EPOCH};
mod options;
pub use options::{MdBookOptions, except_mdbook_common_resources};
mod helper;
/// Builds the books found in [`doc_root`](MdBookOptions::doc_root) into
/// [`doc_static`](MdBookOptions::doc_static) and bundles the result.
///
/// A book is any directory with a `book.toml` file; books are not expected to contain other books.
/// Each one is built into the same relative path under `doc_static`, and only when it changed since
/// the last build, its destination is missing, or [`force_rebuild`](MdBookOptions::force_rebuild)
/// is set. The time of the last build of each book is kept in `doc_static/build_state.txt`.
///
/// Fails if `mdbook` is not available, if `doc_static` is inside `doc_root`, or if a book cannot be
/// built.
pub fn mdbooks_and_bundle(options: MdBookOptions) -> io::Result<()> {
let mdbook_available = std::process::Command::new("mdbook")
.arg("--version")
.output()
.map(|output| output.status.success())
.unwrap_or(false);
if !mdbook_available {
return Err(io::Error::new(
io::ErrorKind::NotFound,
"mdBook is not installed or not on PATH",
));
}
let doc_root = helper::to_absolute(options.doc_root());
let doc_static = helper::to_absolute(options.doc_static());
if doc_static.starts_with(&doc_root) {
return Err(io::Error::other("doc_static must not be inside doc_root"));
}
fs::create_dir_all(&doc_static)?;
// Without it, Cargo would rerun the build script after any change in the package, including
// the files this function writes into `doc_static`, and every build would be dirty.
println!("cargo:rerun-if-changed={}", doc_root.display());
let state_file = doc_static.join("build_state.txt");
let mut state = helper::read_build_state(&state_file)?;
for book_dir in helper::find_mdbooks(&doc_root)? {
let rel_dir = book_dir
.strip_prefix(&doc_root)
.expect("find_mdbooks() only returns directories under doc_root");
let book_key = rel_dir.to_string_lossy().into_owned();
let dest = doc_static.join(rel_dir);
let last_built = state.get(&book_key).copied().unwrap_or(UNIX_EPOCH);
let needs_rebuild = options.force_rebuild()
|| helper::latest_mtime(&book_dir)? > last_built
|| !dest.exists();
if needs_rebuild {
helper::mdbook_build_to_dest(&book_dir, &dest)?;
state.insert(book_key, SystemTime::now());
}
}
helper::write_build_state(&state_file, &state)?;
bundle_only(&doc_static, options.bundle_name(), options.bundle_filter())
}
/// Bundles the files of books already built in `doc_static`, without running mdBook.
///
/// `bundle_name` identifies the bundle in [`serve_mdbook!`](crate::serve_mdbook). With no `filter`,
/// the resources common to every book are left out, because the [`MdBook`](crate::MdBook)
/// extension already serves them (see [`except_mdbook_common_resources()`]).
pub fn bundle_only(
doc_static: &Path,
bundle_name: &str,
filter: Option<fn(&Path) -> bool>,
) -> io::Result<()> {
StaticFilesBundle::from_dir(
helper::to_absolute(doc_static),
filter.or(Some(except_mdbook_common_resources)),
)
.with_name(bundle_name)
.build()
}

122
src/build/helper.rs Normal file
View file

@ -0,0 +1,122 @@
use std::collections::HashMap;
use std::env;
use std::fs::{self, File};
use std::io::{self, BufRead, BufReader, Write};
use std::path::{Path, PathBuf};
use std::process::Command;
use std::time::{Duration, SystemTime, UNIX_EPOCH};
// Resolves a relative path against the root of the package being built.
pub(super) fn to_absolute(path: &Path) -> PathBuf {
if path.is_absolute() {
path.to_path_buf()
} else {
let root = env::var("CARGO_MANIFEST_DIR").unwrap_or_else(|_| ".".into());
Path::new(&root).join(path)
}
}
// Directories under `root` that contain a book. The search does not go into a book.
pub(super) fn find_mdbooks(root: &Path) -> io::Result<Vec<PathBuf>> {
fn walk(dir: &Path, books: &mut Vec<PathBuf>) -> io::Result<()> {
for entry in fs::read_dir(dir)? {
let entry = entry?;
if entry.file_type()?.is_dir() {
let path = entry.path();
if path.join("book.toml").exists() {
books.push(path);
} else {
walk(&path, books)?;
}
}
}
Ok(())
}
let mut books = Vec::new();
walk(root, &mut books)?;
Ok(books)
}
// Most recent modification time of the files under `dir`, or `UNIX_EPOCH` if there are none.
pub(super) fn latest_mtime(dir: &Path) -> io::Result<SystemTime> {
fn visit(dir: &Path, latest: &mut SystemTime) -> io::Result<()> {
for entry in fs::read_dir(dir)? {
let entry = entry?;
let meta = entry.metadata()?;
if meta.is_dir() {
visit(&entry.path(), latest)?;
} else if let Ok(modified) = meta.modified() {
*latest = (*latest).max(modified);
}
}
Ok(())
}
let mut latest = UNIX_EPOCH;
if dir.exists() {
visit(dir, &mut latest)?;
}
Ok(latest)
}
// Builds the book in `book_dir` into `dest`, removing first any previous content of `dest`.
pub(super) fn mdbook_build_to_dest(book_dir: &Path, dest: &Path) -> io::Result<()> {
if dest.exists() {
fs::remove_dir_all(dest)?;
}
if let Some(parent) = dest.parent() {
fs::create_dir_all(parent)?;
}
let built = Command::new("mdbook")
.arg("build")
.arg("--dest-dir")
.arg(dest)
.current_dir(book_dir)
.status()?
.success();
if !built {
return Err(io::Error::other(format!(
"mdBook build failed in {} (dest: {})",
book_dir.display(),
dest.display()
)));
}
Ok(())
}
// Time of the last build of each book, one `<book> <seconds since UNIX_EPOCH>` per line.
pub(super) fn read_build_state(path: &Path) -> io::Result<HashMap<String, SystemTime>> {
let mut state = HashMap::new();
if path.exists() {
for line in BufReader::new(File::open(path)?).lines() {
let line = line?;
let mut fields = line.split_whitespace();
if let (Some(book), Some(secs)) = (fields.next(), fields.next())
&& let Ok(secs) = secs.parse::<u64>()
{
state.insert(book.to_string(), UNIX_EPOCH + Duration::from_secs(secs));
}
}
}
Ok(state)
}
pub(super) fn write_build_state(
path: &Path,
state: &HashMap<String, SystemTime>,
) -> io::Result<()> {
if let Some(parent) = path.parent() {
fs::create_dir_all(parent)?;
}
let mut file = File::create(path)?;
for (book, time) in state {
let secs = time
.duration_since(UNIX_EPOCH)
.map_err(|e| io::Error::other(format!("Invalid system time: {e}")))?
.as_secs();
writeln!(file, "{book} {secs}")?;
}
Ok(())
}

117
src/build/options.rs Normal file
View file

@ -0,0 +1,117 @@
use pagetop::prelude::*;
use std::path::{Path, PathBuf};
// Resources that every book generated by mdBook includes and the `MdBook` extension already serves
// under `/mdbook`.
const COMMON_RESOURCES: [&str; 28] = [
"css/chrome.css",
"css/general.css",
"css/print.css",
"css/variables.css",
"FontAwesome/css/font-awesome.css",
"FontAwesome/fonts/fontawesome-webfont.eot",
"FontAwesome/fonts/fontawesome-webfont.svg",
"FontAwesome/fonts/fontawesome-webfont.ttf",
"FontAwesome/fonts/fontawesome-webfont.woff",
"FontAwesome/fonts/fontawesome-webfont.woff2",
"FontAwesome/fonts/FontAwesome.ttf",
"fonts/fonts.css",
"fonts/OPEN-SANS-LICENSE.txt",
"fonts/open-sans-v17-all-charsets-300.woff2",
"fonts/open-sans-v17-all-charsets-300italic.woff2",
"fonts/open-sans-v17-all-charsets-600.woff2",
"fonts/open-sans-v17-all-charsets-600italic.woff2",
"fonts/open-sans-v17-all-charsets-700.woff2",
"fonts/open-sans-v17-all-charsets-700italic.woff2",
"fonts/open-sans-v17-all-charsets-800.woff2",
"fonts/open-sans-v17-all-charsets-800italic.woff2",
"fonts/open-sans-v17-all-charsets-italic.woff2",
"fonts/open-sans-v17-all-charsets-regular.woff2",
"fonts/SOURCE-CODE-PRO-LICENSE.txt",
"fonts/source-code-pro-v11-all-charsets-500.woff2",
"ayu-highlight.css",
"highlight.css",
"tomorrow-night.css",
];
/// Bundle filter that leaves out the resources common to every book.
///
/// Returns `false` for the styles, fonts and syntax highlighting files that mdBook copies into each
/// book, which the [`MdBook`](crate::MdBook) extension already serves under `/mdbook`.
pub fn except_mdbook_common_resources(path: &Path) -> bool {
!COMMON_RESOURCES.iter().any(|file| path.ends_with(file))
}
/// Options to build and bundle the books of an application (see
/// [`mdbooks_and_bundle()`](super::mdbooks_and_bundle)).
#[derive(AutoDefault, Clone, Debug, Getters)]
pub struct MdBookOptions {
/// Returns the directory searched recursively for books. Defaults to `./doc`.
#[default(_code = "PathBuf::from(\"./doc\")")]
doc_root: PathBuf,
/// Returns the directory for the built books, which keeps the relative path of each book.
/// Defaults to `./static/doc`.
#[default(_code = "PathBuf::from(\"./static/doc\")")]
doc_static: PathBuf,
/// Returns the name of the bundle, used in [`serve_mdbook!`](crate::serve_mdbook). Defaults to
/// `"doc"`.
#[default = "doc"]
bundle_name: String,
/// Returns the filter that selects the files to bundle. Defaults to
/// [`except_mdbook_common_resources()`].
#[getters(copy)]
#[default(_code = "Some(except_mdbook_common_resources)")]
bundle_filter: Option<fn(&Path) -> bool>,
/// Returns whether every book is built, even if it did not change. Defaults to `false`.
#[getters(copy)]
force_rebuild: bool,
}
impl MdBookOptions {
/// Creates the default options.
pub fn new() -> Self {
Self::default()
}
// **< MdBookOptions BUILDER >******************************************************************
/// Sets the directory searched recursively for books, relative to the package root unless it
/// is absolute.
#[builder_fn]
pub fn with_doc_root(mut self, path: impl AsRef<Path>) -> Self {
self.doc_root = path.as_ref().into();
self
}
/// Sets the directory for the built books, relative to the package root unless it is absolute.
///
/// It must not be inside the [`doc_root`](Self::doc_root) directory.
#[builder_fn]
pub fn with_doc_static(mut self, path: impl AsRef<Path>) -> Self {
self.doc_static = path.as_ref().into();
self
}
/// Sets the name of the bundle.
#[builder_fn]
pub fn with_bundle_name(mut self, name: impl Into<String>) -> Self {
self.bundle_name = name.into();
self
}
/// Sets the filter that selects the files to bundle. With `None`, the resources common to every
/// book are left out.
#[builder_fn]
pub fn with_bundle_filter(mut self, filter: impl Into<Option<fn(&Path) -> bool>>) -> Self {
self.bundle_filter = filter.into();
self
}
/// Sets whether every book is built, even if it did not change.
#[builder_fn]
pub fn with_force_rebuild(mut self, rebuild: bool) -> Self {
self.force_rebuild = rebuild;
self
}
}

299
src/lib.rs Normal file
View file

@ -0,0 +1,299 @@
/*!
<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.
*/
#![doc(
html_favicon_url = "https://git.cillero.es/manuelcillero/pagetop/raw/branch/main/static/favicon.ico"
)]
use pagetop::prelude::*;
use std::collections::HashMap;
use std::sync::Arc;
// Used by the code that `serve_mdbook!` expands in the application.
#[doc(hidden)]
pub use pagetop;
pub mod build;
include_locales!(LOCALES_MDBOOK);
/// Extension that serves the resources shared by every mdBook book.
///
/// Styles, fonts and scripts common to all books are embedded once and served under `/mdbook`, so
/// the bundles of the application only carry the content of each book. Declare it as a dependency
/// of the application:
///
/// ```rust,no_run
/// use pagetop::prelude::*;
///
/// struct MyApp;
///
/// #[async_trait]
/// impl Extension for MyApp {
/// fn dependencies(&self) -> Vec<ExtensionRef> {
/// vec![&pagetop_mdbook::MdBook]
/// }
/// }
/// ```
pub struct MdBook;
#[async_trait]
impl Extension for MdBook {
fn name(&self) -> Lc {
Lc::t("extension_name", &LOCALES_MDBOOK)
}
fn description(&self) -> Lc {
Lc::t("extension_description", &LOCALES_MDBOOK)
}
fn configure_static_files(&self, router: Router) -> Router {
serve_static_files!(router, [mdbook] => "/mdbook");
router
}
}
/// Publishes a bundle of mdBook books under a route of the application.
///
/// The bundle is the one generated in `build.rs` with [`build::mdbooks_and_bundle()`] or
/// [`build::bundle_only()`], identified by its name. Every chapter (`.html` file) becomes a PageTop
/// page rendered inside the active theme; the rest of the files (images, scripts, search index...)
/// are served as static files.
///
/// Like [`serve_static_files!`](pagetop::serve_static_files), the macro shadows `router`, so the
/// parameter does not need `mut`, but it must be returned at the end.
///
/// ```rust,ignore
/// use pagetop::prelude::*;
///
/// struct MyApp;
///
/// #[async_trait]
/// impl Extension for MyApp {
/// fn configure_router(&self, router: Router) -> Router {
/// // Chapters are served at /doc/<book path>/<chapter>.html.
/// pagetop_mdbook::serve_mdbook!(router, [doc] => "/doc");
/// router
/// }
/// }
/// ```
#[macro_export]
macro_rules! serve_mdbook {
( $router:ident, [$bundle:ident] => $path:expr $(,)? ) => {
let $router = {
let _span =
$crate::pagetop::trace::debug_span!("serve_mdbook", route = $path).entered();
$crate::pagetop::util::paste! {
mod [<mdbook_files_ $bundle>] {
include!(concat!(env!("OUT_DIR"), "/", stringify!($bundle), ".rs"));
}
$crate::route_books($router, $path, [<mdbook_files_ $bundle>]::$bundle())
}
};
};
}
// A chapter of a book, already split from the header written by the mdBook template.
struct Chapter {
title: Option<&'static str>,
language: Option<&'static str>,
body: &'static str,
}
impl Chapter {
// Template mark after which the chapter content starts. Everything before it (metadata and
// the mdBook header) is replaced by the PageTop page.
const BODY_MARK: &str = "<!-- mdBook -->";
fn parse(html: &'static str) -> Self {
let body = match html.find(Self::BODY_MARK) {
Some(pos) => &html[pos + Self::BODY_MARK.len()..],
None => html,
};
Chapter {
title: metadata("Title", html),
language: metadata("Lang", html),
body,
}
}
async fn render(&self, request: HttpRequest) -> Result<Markup, ErrorPage> {
let mut page = Page::new(request);
if let Some(title) = self.title {
page = page.with_title(Lc::n(title));
}
// The language of the book overrides the negotiated one, if the application supports it.
if let Some(language) = self.language {
let locale = Locale::resolve(language);
if locale.as_option().is_some() {
page = page.with_langid(&locale);
}
}
let body = self.body;
page.with_metadata("theme-color", "#ffffff")
.with_assets(stylesheet("css/variables.css"))
.with_assets(stylesheet("css/general.css"))
.with_assets(stylesheet("css/chrome.css"))
.with_assets(stylesheet("css/print.css").for_media(TargetMedia::Print))
.with_assets(stylesheet("FontAwesome/css/font-awesome.css"))
.with_assets(stylesheet("fonts/fonts.css"))
// Not versioned: `book.js` finds them by the end of their URL to switch themes.
.with_assets(StyleSheet::from("/mdbook/highlight.css"))
.with_assets(StyleSheet::from("/mdbook/tomorrow-night.css"))
.with_assets(StyleSheet::from("/mdbook/ayu-highlight.css"))
.with_assets(
JavaScript::defer("/mdbook/navigators.js").with_version(env!("CARGO_PKG_VERSION")),
)
.with_child(Html::with(move |_| {
html! {
div id="mdbook" { (PreEscaped(body)) }
}
}))
.render()
.await
}
}
fn stylesheet(path: &'static str) -> StyleSheet {
StyleSheet::from(util::join!("/mdbook/", path)).with_version(env!("CARGO_PKG_VERSION"))
}
// Value of a metadata item written by the mdBook template as a `<!-- Name: value -->` comment.
fn metadata(name: &str, html: &'static str) -> Option<&'static str> {
let prefix = util::join!("<!-- ", name, ":");
let start = html.find(&prefix)? + prefix.len();
let len = html[start..].find("-->")?;
util::non_blank(&html[start..start + len])
}
#[doc(hidden)]
pub fn route_books(
mut router: Router,
path: &'static str,
files: HashMap<&'static str, pagetop::StaticFile>,
) -> Router {
let path = path.trim_end_matches('/');
let (chapters, resources): (HashMap<_, _>, HashMap<_, _>) = files
.into_iter()
.partition(|(name, _)| name.ends_with(".html"));
for (name, file) in chapters {
let Ok(html) = std::str::from_utf8(file.data) else {
trace::warn!("Skipping mdBook chapter \"{name}\": it is not valid UTF-8");
continue;
};
let chapter = Arc::new(Chapter::parse(html));
router = router.route(
&util::join!(path, "/", name),
web::get(move |request: HttpRequest| {
let chapter = Arc::clone(&chapter);
async move { chapter.render(request).await }
}),
);
}
router.nest_service(path, web::ServeEmbedded::new(resources))
}

View file

@ -0,0 +1,2 @@
extension_name = mdBook
extension_description = Embeds books generated by mdBook into PageTop applications.

View file

@ -0,0 +1,2 @@
extension_name = mdBook
extension_description = Integra libros generados con mdBook en aplicaciones PageTop.

File diff suppressed because one or more lines are too long

Binary file not shown.

Binary file not shown.

File diff suppressed because it is too large Load diff

After

Width:  |  Height:  |  Size: 434 KiB

Binary file not shown.

Binary file not shown.

Binary file not shown.

78
static/ayu-highlight.css Normal file
View file

@ -0,0 +1,78 @@
/*
Based off of the Ayu theme
Original by Dempfi (https://github.com/dempfi/ayu)
*/
.hljs {
display: block;
overflow-x: auto;
background: #191f26;
color: #e6e1cf;
}
.hljs-comment,
.hljs-quote {
color: #5c6773;
font-style: italic;
}
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-attr,
.hljs-regexp,
.hljs-link,
.hljs-selector-id,
.hljs-selector-class {
color: #ff7733;
}
.hljs-number,
.hljs-meta,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #ffee99;
}
.hljs-string,
.hljs-bullet {
color: #b8cc52;
}
.hljs-title,
.hljs-built_in,
.hljs-section {
color: #ffb454;
}
.hljs-keyword,
.hljs-selector-tag,
.hljs-symbol {
color: #ff7733;
}
.hljs-name {
color: #36a3d9;
}
.hljs-tag {
color: #00568d;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #91b362;
}
.hljs-deletion {
color: #d96c75;
}

621
static/css/chrome.css Normal file
View file

@ -0,0 +1,621 @@
/* CSS for UI elements (a.k.a. chrome) */
@import 'variables.css';
#mdbook {
position: relative;
scrollbar-color: var(--scrollbar) var(--bg);
}
#mdbook .content {
position: relative;
}
#searchresults a,
#mdbook .content a:link,
#mdbook a:visited,
#mdbook a > .hljs {
color: var(--links);
}
/*
body-container is necessary because mobile browsers don't seem to like
overflow-x on the body tag when there is a <meta name="viewport"> tag.
*/
#mdbook .flex__content {
/*
This is used when the sidebar pushes the body content off the side of
the screen on small screens. Without it, dragging on mobile Safari
will want to reposition the viewport in a weird way.
*/
overflow-x: clip;
}
/* Menu Bar */
#menu-bar,
#menu-bar-hover-placeholder {
z-index: 101;
margin: auto calc(0px - var(--page-padding));
}
#menu-bar {
position: relative;
display: flex;
flex-wrap: wrap;
background-color: var(--bg);
border-block-end: 0;
}
#menu-bar.sticky,
.js #menu-bar-hover-placeholder:hover + #menu-bar,
.js #menu-bar:hover,
.js.sidebar-visible #menu-bar {
position: -webkit-sticky;
position: sticky;
top: 0 !important;
}
#menu-bar-hover-placeholder {
position: sticky;
position: -webkit-sticky;
top: 0;
height: var(--menu-bar-height);
}
#menu-bar.bordered {
border-block-end-color: var(--table-border-color);
}
#menu-bar i, #menu-bar .icon-button {
position: relative;
padding: 0 8px;
z-index: 10;
line-height: var(--menu-bar-height);
cursor: pointer;
transition: color 0.5s;
}
@media only screen and (max-width: 420px) {
#menu-bar i, #menu-bar .icon-button {
padding: 0 5px;
}
}
#mdbook .icon-button {
border: none;
background: none;
padding: 0;
color: inherit;
}
#mdbook .icon-button i {
margin: 0;
}
#mdbook .right-buttons {
margin: 0 15px;
}
#mdbook .right-buttons a {
text-decoration: none;
}
#mdbook .left-buttons {
display: flex;
margin: 0 5px;
}
.no-js #mdbook .left-buttons button {
display: none;
}
#mdbook .menu-title {
display: inline-block;
font-weight: 200;
font-size: 1.8rem;
line-height: var(--menu-bar-height);
text-align: center;
margin: 0;
flex: 1;
white-space: nowrap;
overflow: hidden;
text-overflow: ellipsis;
}
.js #mdbook .menu-title {
cursor: pointer;
}
@media only screen and (max-width: 640px) {
#mdbook .menu-title {
font-size: 1.5rem;
}
}
@media only screen and (max-width: 420px) {
#mdbook .menu-title {
font-size: 1.2rem;
}
}
#mdbook .menu-bar,
#mdbook .menu-bar:visited,
#mdbook .nav-chapters,
#mdbook .nav-chapters:visited,
#mdbook .mobile-nav-chapters,
#mdbook .mobile-nav-chapters:visited,
#mdbook .menu-bar .icon-button,
#mdbook .menu-bar a i {
color: var(--icons);
}
#mdbook .menu-bar i:hover,
#mdbook .menu-bar .icon-button:hover,
#mdbook .nav-chapters:hover,
#mdbook .mobile-nav-chapters i:hover {
color: var(--icons-hover);
}
/* Nav Icons */
#mdbook .nav-chapters {
font-size: 2.5em;
text-align: center;
text-decoration: none;
position: absolute;
top: 0;
bottom: 0;
margin: 1rem;
max-width: 150px;
min-width: 90px;
transition: color 0.5s, background-color 0.5s;
}
#mdbook .nav-chapters > i.fa {
display: block;
padding: 50px 0;
visibility: hidden;
}
#mdbook .nav-chapters:hover {
text-decoration: none;
background-color: var(--theme-hover);
transition: background-color 0.15s, color 0.15s;
}
#mdbook .nav-wrapper {
margin-block-start: 50px;
display: none;
}
#mdbook .mobile-nav-chapters {
font-size: 2.5em;
text-align: center;
text-decoration: none;
width: 90px;
border-radius: 5px;
background-color: var(--sidebar-bg);
}
/* Only Firefox supports flow-relative values */
#mdbook .previous {
float: left;
}
[dir=rtl] #mdbook .previous { float: right; }
/* Only Firefox supports flow-relative values */
#mdbook .next {
float: right;
right: var(--page-padding);
}
[dir=rtl] #mdbook .next {
float: left;
right: unset;
left: var(--page-padding);
}
/* Use the correct buttons for RTL layouts*/
[dir=rtl] #mdbook .previous i.fa-angle-left:before { content:"\f105"; }
[dir=rtl] #mdbook .next i.fa-angle-right:before { content:"\f104"; }
@media only screen and (max-width: 1080px) {
#mdbook .nav-wide-wrapper { display: none; }
#mdbook .nav-wrapper { display: block; }
}
/* sidebar-visible */
@media only screen and (max-width: 1380px) {
#sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wide-wrapper { display: none; }
#sidebar-toggle-anchor:checked ~ .page-wrapper .nav-wrapper { display: block; }
}
/* Inline code */
#mdbook :not(pre) > .hljs {
display: inline;
padding: 0.1em 0.3em;
border-radius: 3px;
}
#mdbook :not(pre):not(a) > .hljs {
color: var(--inline-code-color);
overflow-x: initial;
}
#mdbook a:hover > .hljs {
text-decoration: underline;
}
#mdbook pre {
position: relative;
}
#mdbook pre > .buttons {
position: absolute;
z-index: 100;
right: 0px;
top: 2px;
margin: 0px;
padding: 2px 0px;
color: var(--sidebar-fg);
cursor: pointer;
visibility: hidden;
opacity: 0;
transition: visibility 0.1s linear, opacity 0.1s linear;
}
#mdbook pre:hover > .buttons {
visibility: visible;
opacity: 1
}
#mdbook pre > .buttons :hover {
color: var(--sidebar-active);
border-color: var(--icons-hover);
background-color: var(--theme-hover);
}
#mdbook pre > .buttons i {
margin-inline-start: 8px;
}
#mdbook pre > .buttons button {
cursor: inherit;
margin: 0px 5px;
padding: 3px 5px;
font-size: 14px;
border-style: solid;
border-width: 1px;
border-radius: 4px;
border-color: var(--icons);
background-color: var(--theme-popup-bg);
transition: 100ms;
transition-property: color,border-color,background-color;
color: var(--icons);
}
@media (pointer: coarse) {
#mdbook pre > .buttons button {
/* On mobile, make it easier to tap buttons. */
padding: 0.3rem 1rem;
}
#mdbook .sidebar-resize-indicator {
/* Hide resize indicator on devices with limited accuracy */
display: none;
}
}
#mdbook pre > code {
display: block;
padding: 1rem;
}
/* FIXME: ACE editors overlap their buttons because ACE does absolute
positioning within the code block which breaks padding. The only solution I
can think of is to move the padding to the outer pre tag (or insert a div
wrapper), but that would require fixing a whole bunch of CSS rules.
*/
#mdbook .hljs.ace_editor {
padding: 0rem 0rem;
}
#mdbook pre > .result {
margin-block-start: 10px;
}
/* Search */
#searchresults a {
text-decoration: none;
}
#mdbook mark {
border-radius: 2px;
padding-block-start: 0;
padding-block-end: 1px;
padding-inline-start: 3px;
padding-inline-end: 3px;
margin-block-start: 0;
margin-block-end: -1px;
margin-inline-start: -3px;
margin-inline-end: -3px;
background-color: var(--search-mark-bg);
transition: background-color 300ms linear;
cursor: pointer;
}
#mdbook mark.fade-out {
background-color: rgba(0,0,0,0) !important;
cursor: auto;
}
#mdbook .searchbar-outer {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
}
#searchbar {
width: 100%;
margin-block-start: 5px;
margin-block-end: 0;
margin-inline-start: auto;
margin-inline-end: auto;
padding: 10px 16px;
transition: box-shadow 300ms ease-in-out;
border: 1px solid var(--searchbar-border-color);
border-radius: 3px;
background-color: var(--searchbar-bg);
color: var(--searchbar-fg);
}
#searchbar:focus,
#searchbar.active {
box-shadow: 0 0 3px var(--searchbar-shadow-color);
}
#mdbook .searchresults-header {
font-weight: bold;
font-size: 1em;
padding-block-start: 18px;
padding-block-end: 0;
padding-inline-start: 5px;
padding-inline-end: 0;
color: var(--searchresults-header-fg);
}
#mdbook .searchresults-outer {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
border-block-end: 1px dashed var(--searchresults-border-color);
}
#mdbook ul#searchresults {
list-style: none;
padding-inline-start: 20px;
}
#mdbook ul#searchresults li {
margin: 10px 0px;
padding: 2px;
border-radius: 2px;
}
#mdbook ul#searchresults li.focus {
background-color: var(--searchresults-li-bg);
}
#mdbook ul#searchresults span.teaser {
display: block;
clear: both;
margin-block-start: 5px;
margin-block-end: 0;
margin-inline-start: 20px;
margin-inline-end: 0;
font-size: 0.8em;
}
#mdbook ul#searchresults span.teaser em {
font-weight: bold;
font-style: normal;
}
/* Sidebar */
#mdbook .sidebar {
position: absolute;
left: 0;
top: 0;
bottom: 0;
width: var(--sidebar-width);
font-size: 0.875em;
box-sizing: border-box;
-webkit-overflow-scrolling: touch;
overscroll-behavior-y: contain;
background-color: var(--sidebar-bg);
color: var(--sidebar-fg);
}
[dir=rtl] #mdbook .sidebar { left: unset; right: 0; }
#mdbook .sidebar-resizing {
-moz-user-select: none;
-webkit-user-select: none;
-ms-user-select: none;
user-select: none;
}
.no-js #mdbook .sidebar,
.js:not(.sidebar-resizing) #mdbook .sidebar {
transition: transform 0.3s; /* Animation: slide away */
}
#mdbook .sidebar code {
line-height: 2em;
}
#mdbook .sidebar .sidebar-scrollbox {
overflow-y: auto;
position: absolute;
top: 0;
bottom: 0;
left: 0;
right: 0;
padding: 10px 10px;
}
#mdbook .sidebar .sidebar-resize-handle {
position: absolute;
cursor: col-resize;
width: 0;
right: calc(var(--sidebar-resize-indicator-width) * -1);
top: 0;
bottom: 0;
display: flex;
align-items: center;
}
#mdbook .sidebar-resize-handle .sidebar-resize-indicator {
width: 100%;
height: 30px;
background-color: var(--icons);
margin-inline-start: var(--sidebar-resize-indicator-space);
}
[dir=rtl] #mdbook .sidebar .sidebar-resize-handle {
left: calc(var(--sidebar-resize-indicator-width) * -1);
right: unset;
}
.js #mdbook .sidebar .sidebar-resize-handle {
cursor: col-resize;
width: calc(var(--sidebar-resize-indicator-width) - var(--sidebar-resize-indicator-space));
}
/* sidebar-hidden */
#sidebar-toggle-anchor:not(:checked) ~ .sidebar {
transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
z-index: -1;
}
[dir=rtl] #sidebar-toggle-anchor:not(:checked) ~ .sidebar {
transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
}
#mdbook .sidebar::-webkit-scrollbar {
background: var(--sidebar-bg);
}
#mdbook .sidebar::-webkit-scrollbar-thumb {
background: var(--scrollbar);
}
/* sidebar-visible */
#sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: translateX(calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width)));
}
[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: translateX(calc(0px - var(--sidebar-width) - var(--sidebar-resize-indicator-width)));
}
@media only screen and (min-width: 620px) {
#sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: none;
margin-inline-start: calc(var(--sidebar-width) + var(--sidebar-resize-indicator-width));
}
[dir=rtl] #sidebar-toggle-anchor:checked ~ .page-wrapper {
transform: none;
}
}
#mdbook .chapter {
list-style: none outside none;
padding-inline-start: 0;
line-height: 2.2em;
}
#mdbook .chapter ol {
width: 100%;
}
#mdbook .chapter li {
display: flex;
color: var(--sidebar-non-existant);
}
#mdbook .chapter li a {
display: block;
padding: 0;
text-decoration: none;
color: var(--sidebar-fg);
}
#mdbook .chapter li a:hover {
color: var(--sidebar-active);
}
#mdbook .chapter li a.active {
color: var(--sidebar-active);
}
#mdbook .chapter li > a.toggle {
cursor: pointer;
display: block;
margin-inline-start: auto;
padding: 0 10px;
user-select: none;
opacity: 0.68;
}
#mdbook .chapter li > a.toggle div {
transition: transform 0.5s;
}
/* collapse the section */
#mdbook .chapter li:not(.expanded) + li > ol {
display: none;
}
#mdbook .chapter li.chapter-item {
line-height: 1.5em;
margin-block-start: 0.6em;
}
#mdbook .chapter li.expanded > a.toggle div {
transform: rotate(90deg);
}
#mdbook .spacer {
width: 100%;
height: 3px;
margin: 5px 0px;
}
#mdbook .chapter .spacer {
background-color: var(--sidebar-spacer);
}
@media (-moz-touch-enabled: 1), (pointer: coarse) {
#mdbook .chapter li a { padding: 5px 0; }
#mdbook .spacer { margin: 10px 0; }
}
#mdbook .section {
list-style: none outside none;
padding-inline-start: 20px;
line-height: 1.9em;
}
/* Theme Menu Popup */
#mdbook .theme-popup {
position: absolute;
left: 10px;
top: var(--menu-bar-height);
z-index: 1000;
border-radius: 4px;
font-size: 0.7em;
color: var(--fg);
background: var(--theme-popup-bg);
border: 1px solid var(--theme-popup-border);
margin: 0;
padding: 0;
list-style: none;
display: none;
/* Don't let the children's background extend past the rounded corners. */
overflow: hidden;
}
[dir=rtl] #mdbook .theme-popup { left: unset; right: 10px; }
#mdbook .theme-popup .default {
color: var(--icons);
}
#mdbook .theme-popup .theme {
width: 100%;
border: 0;
margin: 0;
padding: 2px 20px;
line-height: 25px;
white-space: nowrap;
text-align: start;
cursor: pointer;
color: inherit;
background: inherit;
font-size: inherit;
}
#mdbook .theme-popup .theme:hover {
background-color: var(--theme-hover);
}
#mdbook .theme-selected::before {
display: inline-block;
content: "✓";
margin-inline-start: -14px;
width: 14px;
}

228
static/css/general.css Normal file
View file

@ -0,0 +1,228 @@
/* Base styles and content styles */
@import 'variables.css';
#mdbook {
font-family: "Open Sans", sans-serif;
color: var(--fg);
background-color: var(--bg);
text-size-adjust: none;
-webkit-text-size-adjust: none;
overflow-x: hidden;
}
#mdbook code {
font-family: var(--mono-font) !important;
font-size: var(--code-font-size);
direction: ltr !important;
}
/* make long words/inline code not x overflow */
#mdbook main {
overflow-wrap: break-word;
}
/* make wide tables scroll if they overflow */
#mdbook .table-wrapper {
overflow-x: auto;
}
/* Don't change font size in headers. */
#mdbook h1 code,
#mdbook h2 code,
#mdbook h3 code,
#mdbook h4 code,
#mdbook h5 code,
#mdbook h6 code {
font-size: unset;
}
#mdbook .left { float: left; }
#mdbook .right { float: right; }
#mdbook .boring { opacity: 0.6; }
#mdbook .hide-boring .boring { display: none; }
#mdbook .hidden { display: none !important; }
#mdbook h1 { margin-block-start: 1.2em; }
#mdbook h2, #mdbook h3 { margin-block-start: 1em; }
#mdbook h4, #mdbook h5 { margin-block-start: 2em; }
#mdbook .header + .header h3,
#mdbook .header + .header h4,
#mdbook .header + .header h5 {
margin-block-start: 1em;
}
#mdbook h1:target::before,
#mdbook h2:target::before,
#mdbook h3:target::before,
#mdbook h4:target::before,
#mdbook h5:target::before,
#mdbook h6:target::before {
display: inline-block;
content: "»";
margin-inline-start: -30px;
width: 30px;
}
/* This is broken on Safari as of version 14, but is fixed
in Safari Technology Preview 117 which I think will be Safari 14.2.
https://bugs.webkit.org/show_bug.cgi?id=218076
*/
:target {
scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
}
#mdbook .page {
outline: 0;
padding: 0 var(--page-padding);
margin-block-start: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
}
#mdbook .page-wrapper {
box-sizing: border-box;
background-color: var(--bg);
}
.no-js #mdbook .page-wrapper,
.js:not(.sidebar-resizing) #mdbook .page-wrapper {
transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
}
[dir=rtl] .js:not(.sidebar-resizing) #mdbook .page-wrapper {
transition: margin-right 0.3s ease, transform 0.3s ease; /* Animation: slide away */
}
#mdbook .content {
overflow-y: auto;
padding: 0 5px 50px 5px;
}
#mdbook .content main {
margin-inline-start: auto;
margin-inline-end: auto;
max-width: var(--content-max-width);
}
#mdbook .content p { line-height: 1.45em; }
#mdbook .content ol { line-height: 1.45em; }
#mdbook .content ul { line-height: 1.45em; }
#mdbook .content a { text-decoration: none; }
#mdbook .content a:hover { text-decoration: underline; }
#mdbook .content img, .content video { max-width: 100%; }
#mdbook .content .header:link,
#mdbook .content .header:visited {
color: var(--fg);
}
#mdbook .content .header:link,
#mdbook .content .header:visited:hover {
text-decoration: none;
}
#mdbook table {
margin: 0 auto;
border-collapse: collapse;
}
#mdbook table td {
padding: 3px 20px;
border: 1px var(--table-border-color) solid;
}
#mdbook table thead {
background: var(--table-header-bg);
}
#mdbook table thead td {
font-weight: 700;
border: none;
}
#mdbook table thead th {
padding: 3px 20px;
}
#mdbook table thead tr {
border: 1px var(--table-header-bg) solid;
}
/* Alternate background colors for rows */
#mdbook table tbody tr:nth-child(2n) {
background: var(--table-alternate-bg);
}
#mdbook blockquote {
margin: 20px 0;
padding: 0 20px;
color: var(--fg);
background-color: var(--quote-bg);
border-block-start: .1em solid var(--quote-border);
border-block-end: .1em solid var(--quote-border);
}
#mdbook .warning {
margin: 20px;
padding: 0 20px;
border-inline-start: 2px solid var(--warning-border);
}
#mdbook .warning:before {
position: absolute;
width: 3rem;
height: 3rem;
margin-inline-start: calc(-1.5rem - 21px);
content: "ⓘ";
text-align: center;
background-color: var(--bg);
color: var(--warning-border);
font-weight: bold;
font-size: 2rem;
}
#mdbook blockquote .warning:before {
background-color: var(--quote-bg);
}
#mdbook kbd {
background-color: var(--table-border-color);
border-radius: 4px;
border: solid 1px var(--theme-popup-border);
box-shadow: inset 0 -1px 0 var(--theme-hover);
display: inline-block;
font-size: var(--code-font-size);
font-family: var(--mono-font);
line-height: 10px;
padding: 4px 5px;
vertical-align: middle;
}
#mdbook :not(.footnote-definition) + .footnote-definition,
#mdbook .footnote-definition + :not(.footnote-definition) {
margin-block-start: 2em;
}
#mdbook .footnote-definition {
font-size: 0.9em;
margin: 0.5em 0;
}
#mdbook .footnote-definition p {
display: inline;
}
#mdbook .tooltiptext {
position: absolute;
visibility: hidden;
color: #fff;
background-color: #333;
transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
left: -8px; /* Half of the width of the icon */
top: -35px;
font-size: 0.8em;
text-align: center;
border-radius: 6px;
padding: 5px 8px;
margin: 5px;
z-index: 1000;
}
#mdbook .tooltipped .tooltiptext {
visibility: visible;
}
#mdbook .chapter li.part-title {
color: var(--sidebar-fg);
margin: 5px 0px;
font-weight: bold;
}
#mdbook .result-no-output {
font-style: italic;
}

59
static/css/print.css Normal file
View file

@ -0,0 +1,59 @@
#sidebar,
#menu-bar,
#mdbook .nav-chapters,
#mdbook .mobile-nav-chapters {
display: none;
}
#mdbook,
#page-wrapper.page-wrapper {
transform: none !important;
margin-inline-start: 0px;
overflow-y: initial;
}
#content {
max-width: none;
margin: 0;
padding: 0;
}
#mdbook .page {
overflow-y: initial;
}
#mdbook code {
direction: ltr !important;
}
#mdbook pre > .buttons {
z-index: 2;
}
#mdbook a,
#mdbook a:visited,
#mdbook a:active,
#mdbook a:hover {
color: #4183c4;
text-decoration: none;
}
#mdbook h1,
#mdbook h2,
#mdbook h3,
#mdbook h4,
#mdbook h5,
#mdbook h6 {
page-break-inside: avoid;
page-break-after: avoid;
}
#mdbook pre,
#mdbook code {
page-break-inside: avoid;
white-space: pre-wrap;
}
#mdbook .fa {
display: none !important;
}

279
static/css/variables.css Normal file
View file

@ -0,0 +1,279 @@
/* Globals */
:root {
--sidebar-width: 300px;
--sidebar-resize-indicator-width: 6px;
--sidebar-resize-indicator-space: 2px;
--page-padding: 15px;
--content-max-width: 750px;
--menu-bar-height: 50px;
--mono-font: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace;
--code-font-size: 0.875em /* please adjust the ace font size accordingly in editor.js */
}
/* Themes */
.ayu {
--bg: hsl(210, 25%, 8%);
--fg: #c5c5c5;
--sidebar-bg: #14191f;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #5c6773;
--sidebar-active: #ffb454;
--sidebar-spacer: #2d334f;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #b7b9cc;
--links: #0096cf;
--inline-code-color: #ffb454;
--theme-popup-bg: #14191f;
--theme-popup-border: #5c6773;
--theme-hover: #191f26;
--quote-bg: hsl(226, 15%, 17%);
--quote-border: hsl(226, 15%, 22%);
--warning-border: #ff8e00;
--table-border-color: hsl(210, 25%, 13%);
--table-header-bg: hsl(210, 25%, 28%);
--table-alternate-bg: hsl(210, 25%, 11%);
--searchbar-border-color: #848484;
--searchbar-bg: #424242;
--searchbar-fg: #fff;
--searchbar-shadow-color: #d4c89f;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #252932;
--search-mark-bg: #e3b171;
--color-scheme: dark;
}
.coal {
--bg: hsl(200, 7%, 8%);
--fg: #98a3ad;
--sidebar-bg: #292c2f;
--sidebar-fg: #a1adb8;
--sidebar-non-existant: #505254;
--sidebar-active: #3473ad;
--sidebar-spacer: #393939;
--scrollbar: var(--sidebar-fg);
--icons: #43484d;
--icons-hover: #b3c0cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #141617;
--theme-popup-border: #43484d;
--theme-hover: #1f2124;
--quote-bg: hsl(234, 21%, 18%);
--quote-border: hsl(234, 21%, 23%);
--warning-border: #ff8e00;
--table-border-color: hsl(200, 7%, 13%);
--table-header-bg: hsl(200, 7%, 28%);
--table-alternate-bg: hsl(200, 7%, 11%);
--searchbar-border-color: #aaa;
--searchbar-bg: #b7b7b7;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #98a3ad;
--searchresults-li-bg: #2b2b2f;
--search-mark-bg: #355c7d;
--color-scheme: dark;
}
.light {
--bg: hsl(0, 0%, 100%);
--fg: hsl(0, 0%, 0%);
--sidebar-bg: #fafafa;
--sidebar-fg: hsl(0, 0%, 0%);
--sidebar-non-existant: #aaaaaa;
--sidebar-active: #1f1fff;
--sidebar-spacer: #f4f4f4;
--scrollbar: #8F8F8F;
--icons: #747474;
--icons-hover: #000000;
--links: #477ed0;
--inline-code-color: #301900;
--theme-popup-bg: #fafafa;
--theme-popup-border: #cccccc;
--theme-hover: #e6e6e6;
--quote-bg: hsl(197, 37%, 96%);
--quote-border: hsl(197, 37%, 91%);
--warning-border: #ff8e00;
--table-border-color: hsl(0, 0%, 95%);
--table-header-bg: hsl(0, 0%, 80%);
--table-alternate-bg: hsl(0, 0%, 97%);
--searchbar-border-color: #aaa;
--searchbar-bg: #fafafa;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #e4f2fe;
--search-mark-bg: #a2cff5;
--color-scheme: light;
}
.navy {
--bg: hsl(226, 23%, 11%);
--fg: #bcbdd0;
--sidebar-bg: #282d3f;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #505274;
--sidebar-active: #2b79a2;
--sidebar-spacer: #2d334f;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #b7b9cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #161923;
--theme-popup-border: #737480;
--theme-hover: #282e40;
--quote-bg: hsl(226, 15%, 17%);
--quote-border: hsl(226, 15%, 22%);
--warning-border: #ff8e00;
--table-border-color: hsl(226, 23%, 16%);
--table-header-bg: hsl(226, 23%, 31%);
--table-alternate-bg: hsl(226, 23%, 14%);
--searchbar-border-color: #aaa;
--searchbar-bg: #aeaec6;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #5f5f71;
--searchresults-border-color: #5c5c68;
--searchresults-li-bg: #242430;
--search-mark-bg: #a2cff5;
--color-scheme: dark;
}
.rust {
--bg: hsl(60, 9%, 87%);
--fg: #262625;
--sidebar-bg: #3b2e2a;
--sidebar-fg: #c8c9db;
--sidebar-non-existant: #505254;
--sidebar-active: #e69f67;
--sidebar-spacer: #45373a;
--scrollbar: var(--sidebar-fg);
--icons: #737480;
--icons-hover: #262625;
--links: #2b79a2;
--inline-code-color: #6e6b5e;
--theme-popup-bg: #e1e1db;
--theme-popup-border: #b38f6b;
--theme-hover: #99908a;
--quote-bg: hsl(60, 5%, 75%);
--quote-border: hsl(60, 5%, 70%);
--warning-border: #ff8e00;
--table-border-color: hsl(60, 9%, 82%);
--table-header-bg: #b3a497;
--table-alternate-bg: hsl(60, 9%, 84%);
--searchbar-border-color: #aaa;
--searchbar-bg: #fafafa;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #888;
--searchresults-li-bg: #dec2a2;
--search-mark-bg: #e69f67;
--color-scheme: light;
}
@media (prefers-color-scheme: dark) {
.light.no-js {
--bg: hsl(200, 7%, 8%);
--fg: #98a3ad;
--sidebar-bg: #292c2f;
--sidebar-fg: #a1adb8;
--sidebar-non-existant: #505254;
--sidebar-active: #3473ad;
--sidebar-spacer: #393939;
--scrollbar: var(--sidebar-fg);
--icons: #43484d;
--icons-hover: #b3c0cc;
--links: #2b79a2;
--inline-code-color: #c5c8c6;
--theme-popup-bg: #141617;
--theme-popup-border: #43484d;
--theme-hover: #1f2124;
--quote-bg: hsl(234, 21%, 18%);
--quote-border: hsl(234, 21%, 23%);
--warning-border: #ff8e00;
--table-border-color: hsl(200, 7%, 13%);
--table-header-bg: hsl(200, 7%, 28%);
--table-alternate-bg: hsl(200, 7%, 11%);
--searchbar-border-color: #aaa;
--searchbar-bg: #b7b7b7;
--searchbar-fg: #000;
--searchbar-shadow-color: #aaa;
--searchresults-header-fg: #666;
--searchresults-border-color: #98a3ad;
--searchresults-li-bg: #2b2b2f;
--search-mark-bg: #355c7d;
}
}

View file

@ -0,0 +1,202 @@
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction,
and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by
the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all
other entities that control, are controlled by, or are under common
control with that entity. For the purposes of this definition,
"control" means (i) the power, direct or indirect, to cause the
direction or management of such entity, whether by contract or
otherwise, or (ii) ownership of fifty percent (50%) or more of the
outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity
exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,
including but not limited to software source code, documentation
source, and configuration files.
"Object" form shall mean any form resulting from mechanical
transformation or translation of a Source form, including but
not limited to compiled object code, generated documentation,
and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or
Object form, made available under the License, as indicated by a
copyright notice that is included in or attached to the work
(an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object
form, that is based on (or derived from) the Work and for which the
editorial revisions, annotations, elaborations, or other modifications
represent, as a whole, an original work of authorship. For the purposes
of this License, Derivative Works shall not include works that remain
separable from, or merely link (or bind by name) to the interfaces of,
the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including
the original version of the Work and any modifications or additions
to that Work or Derivative Works thereof, that is intentionally
submitted to Licensor for inclusion in the Work by the copyright owner
or by an individual or Legal Entity authorized to submit on behalf of
the copyright owner. For the purposes of this definition, "submitted"
means any form of electronic, verbal, or written communication sent
to the Licensor or its representatives, including but not limited to
communication on electronic mailing lists, source code control systems,
and issue tracking systems that are managed by, or on behalf of, the
Licensor for the purpose of discussing and improving the Work, but
excluding communication that is conspicuously marked or otherwise
designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity
on behalf of whom a Contribution has been received by Licensor and
subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
copyright license to reproduce, prepare Derivative Works of,
publicly display, publicly perform, sublicense, and distribute the
Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of
this License, each Contributor hereby grants to You a perpetual,
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
(except as stated in this section) patent license to make, have made,
use, offer to sell, sell, import, and otherwise transfer the Work,
where such license applies only to those patent claims licensable
by such Contributor that are necessarily infringed by their
Contribution(s) alone or by combination of their Contribution(s)
with the Work to which such Contribution(s) was submitted. If You
institute patent litigation against any entity (including a
cross-claim or counterclaim in a lawsuit) alleging that the Work
or a Contribution incorporated within the Work constitutes direct
or contributory patent infringement, then any patent licenses
granted to You under this License for that Work shall terminate
as of the date such litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the
Work or Derivative Works thereof in any medium, with or without
modifications, and in Source or Object form, provided that You
meet the following conditions:
(a) You must give any other recipients of the Work or
Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices
stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works
that You distribute, all copyright, patent, trademark, and
attribution notices from the Source form of the Work,
excluding those notices that do not pertain to any part of
the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its
distribution, then any Derivative Works that You distribute must
include a readable copy of the attribution notices contained
within such NOTICE file, excluding those notices that do not
pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed
as part of the Derivative Works; within the Source form or
documentation, if provided along with the Derivative Works; or,
within a display generated by the Derivative Works, if and
wherever such third-party notices normally appear. The contents
of the NOTICE file are for informational purposes only and
do not modify the License. You may add Your own attribution
notices within Derivative Works that You distribute, alongside
or as an addendum to the NOTICE text from the Work, provided
that such additional attribution notices cannot be construed
as modifying the License.
You may add Your own copyright statement to Your modifications and
may provide additional or different license terms and conditions
for use, reproduction, or distribution of Your modifications, or
for any such Derivative Works as a whole, provided Your use,
reproduction, and distribution of the Work otherwise complies with
the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise,
any Contribution intentionally submitted for inclusion in the Work
by You to the Licensor shall be under the terms and conditions of
this License, without any additional terms or conditions.
Notwithstanding the above, nothing herein shall supersede or modify
the terms of any separate license agreement you may have executed
with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade
names, trademarks, service marks, or product names of the Licensor,
except as required for reasonable and customary use in describing the
origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or
agreed to in writing, Licensor provides the Work (and each
Contributor provides its Contributions) on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
implied, including, without limitation, any warranties or conditions
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
PARTICULAR PURPOSE. You are solely responsible for determining the
appropriateness of using or redistributing the Work and assume any
risks associated with Your exercise of permissions under this License.
8. Limitation of Liability. In no event and under no legal theory,
whether in tort (including negligence), contract, or otherwise,
unless required by applicable law (such as deliberate and grossly
negligent acts) or agreed to in writing, shall any Contributor be
liable to You for damages, including any direct, indirect, special,
incidental, or consequential damages of any character arising as a
result of this License or out of the use or inability to use the
Work (including but not limited to damages for loss of goodwill,
work stoppage, computer failure or malfunction, or any and all
other commercial damages or losses), even if such Contributor
has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing
the Work or Derivative Works thereof, You may choose to offer,
and charge a fee for, acceptance of support, warranty, indemnity,
or other liability obligations and/or rights consistent with this
License. However, in accepting such obligations, You may act only
on Your own behalf and on Your sole responsibility, not on behalf
of any other Contributor, and only if You agree to indemnify,
defend, and hold each Contributor harmless for any liability
incurred by, or claims asserted against, such Contributor by reason
of your accepting any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following
boilerplate notice, with the fields enclosed by brackets "[]"
replaced with your own identifying information. (Don't include
the brackets!) The text should be enclosed in the appropriate
comment syntax for the file format. We also recommend that a
file or class name and description of purpose be included on the
same "printed page" as the copyright notice for easier
identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

View file

@ -0,0 +1,93 @@
Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
This Font Software is licensed under the SIL Open Font License, Version 1.1.
This license is copied below, and is also available with a FAQ at:
http://scripts.sil.org/OFL
-----------------------------------------------------------
SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
-----------------------------------------------------------
PREAMBLE
The goals of the Open Font License (OFL) are to stimulate worldwide
development of collaborative font projects, to support the font creation
efforts of academic and linguistic communities, and to provide a free and
open framework in which fonts may be shared and improved in partnership
with others.
The OFL allows the licensed fonts to be used, studied, modified and
redistributed freely as long as they are not sold by themselves. The
fonts, including any derivative works, can be bundled, embedded,
redistributed and/or sold with any software provided that any reserved
names are not used by derivative works. The fonts and derivatives,
however, cannot be released under any other type of license. The
requirement for fonts to remain under this license does not apply
to any document created using the fonts or their derivatives.
DEFINITIONS
"Font Software" refers to the set of files released by the Copyright
Holder(s) under this license and clearly marked as such. This may
include source files, build scripts and documentation.
"Reserved Font Name" refers to any names specified as such after the
copyright statement(s).
"Original Version" refers to the collection of Font Software components as
distributed by the Copyright Holder(s).
"Modified Version" refers to any derivative made by adding to, deleting,
or substituting -- in part or in whole -- any of the components of the
Original Version, by changing formats or by porting the Font Software to a
new environment.
"Author" refers to any designer, engineer, programmer, technical
writer or other person who contributed to the Font Software.
PERMISSION & CONDITIONS
Permission is hereby granted, free of charge, to any person obtaining
a copy of the Font Software, to use, study, copy, merge, embed, modify,
redistribute, and sell modified and unmodified copies of the Font
Software, subject to the following conditions:
1) Neither the Font Software nor any of its individual components,
in Original or Modified Versions, may be sold by itself.
2) Original or Modified Versions of the Font Software may be bundled,
redistributed and/or sold with any software, provided that each copy
contains the above copyright notice and this license. These can be
included either as stand-alone text files, human-readable headers or
in the appropriate machine-readable metadata fields within text or
binary files as long as those fields can be easily viewed by the user.
3) No Modified Version of the Font Software may use the Reserved Font
Name(s) unless explicit written permission is granted by the corresponding
Copyright Holder. This restriction only applies to the primary font name as
presented to the users.
4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
Software shall not be used to promote, endorse or advertise any
Modified Version, except to acknowledge the contribution(s) of the
Copyright Holder(s) and the Author(s) or with their explicit written
permission.
5) The Font Software, modified or unmodified, in part or in whole,
must be distributed entirely under this license, and must not be
distributed under any other license. The requirement for fonts to
remain under this license does not apply to any document created
using the Font Software.
TERMINATION
This license becomes null and void if any of the above conditions are
not met.
DISCLAIMER
THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
OTHER DEALINGS IN THE FONT SOFTWARE.

100
static/fonts/fonts.css Normal file
View file

@ -0,0 +1,100 @@
/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 300;
src: local('Open Sans Light'), local('OpenSans-Light'),
url('open-sans-v17-all-charsets-300.woff2') format('woff2');
}
/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 300;
src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
url('open-sans-v17-all-charsets-300italic.woff2') format('woff2');
}
/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 400;
src: local('Open Sans Regular'), local('OpenSans-Regular'),
url('open-sans-v17-all-charsets-regular.woff2') format('woff2');
}
/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 400;
src: local('Open Sans Italic'), local('OpenSans-Italic'),
url('open-sans-v17-all-charsets-italic.woff2') format('woff2');
}
/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 600;
src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
url('open-sans-v17-all-charsets-600.woff2') format('woff2');
}
/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 600;
src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
url('open-sans-v17-all-charsets-600italic.woff2') format('woff2');
}
/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 700;
src: local('Open Sans Bold'), local('OpenSans-Bold'),
url('open-sans-v17-all-charsets-700.woff2') format('woff2');
}
/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 700;
src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
url('open-sans-v17-all-charsets-700italic.woff2') format('woff2');
}
/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: normal;
font-weight: 800;
src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
url('open-sans-v17-all-charsets-800.woff2') format('woff2');
}
/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Open Sans';
font-style: italic;
font-weight: 800;
src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
url('open-sans-v17-all-charsets-800italic.woff2') format('woff2');
}
/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
@font-face {
font-family: 'Source Code Pro';
font-style: normal;
font-weight: 500;
src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2');
}

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

82
static/highlight.css Normal file
View file

@ -0,0 +1,82 @@
/*
* An increased contrast highlighting scheme loosely based on the
* "Base16 Atelier Dune Light" theme by Bram de Haan
* (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
* Original Base16 color scheme by Chris Kempson
* (https://github.com/chriskempson/base16)
*/
/* Comment */
.hljs-comment,
.hljs-quote {
color: #575757;
}
/* Red */
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-tag,
.hljs-name,
.hljs-regexp,
.hljs-link,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class {
color: #d70025;
}
/* Orange */
.hljs-number,
.hljs-meta,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #b21e00;
}
/* Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet {
color: #008200;
}
/* Blue */
.hljs-title,
.hljs-section {
color: #0030f2;
}
/* Purple */
.hljs-keyword,
.hljs-selector-tag {
color: #9d00ec;
}
.hljs {
display: block;
overflow-x: auto;
background: #f6f7f6;
color: #000;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #22863a;
background-color: #f0fff4;
}
.hljs-deletion {
color: #b31d28;
background-color: #ffeef0;
}

42
static/navigators.js Normal file
View file

@ -0,0 +1,42 @@
const navChapters = document.querySelectorAll('#mdbook a.nav-chapters');
const calculatePosition = (navChapter) => {
const windowHeight = window.innerHeight;
const navRect = navChapter.getBoundingClientRect();
const navIcon = navChapter.querySelector('i.fa');
const iRect = navIcon.getBoundingClientRect();
// Calculate the vertical central position
let iMiddle = navRect.height / 2 - iRect.height / 2;
if (iMiddle + navRect.top > windowHeight - iRect.height) {
// Positions below until upper edge
iMiddle = Math.max(windowHeight - navRect.top - iRect.height, 0);
} else if (iMiddle + navRect.top < 0) {
// Positions above until lower edge
iMiddle = Math.min(Math.abs(navRect.top), navRect.height - iRect.height);
}
navIcon.style.transform = 'translateY(' + iMiddle + 'px)';
navIcon.style.top = iMiddle + 'px';
navIcon.style.visibility = 'visible';
};
// Initial position
navChapters.forEach((navChapter) => {
calculatePosition(navChapter);
});
// Add a scroll event listener
window.addEventListener('scroll', () => {
navChapters.forEach((navChapter) => {
calculatePosition(navChapter);
});
});
// Add a resize event listener
window.addEventListener('resize', () => {
navChapters.forEach((navChapter) => {
calculatePosition(navChapter);
});
});

102
static/tomorrow-night.css Normal file
View file

@ -0,0 +1,102 @@
/* Tomorrow Night Theme */
/* https://github.com/jmblog/color-themes-for-highlightjs */
/* Original theme - https://github.com/chriskempson/tomorrow-theme */
/* https://github.com/jmblog/color-themes-for-highlightjs */
/* Tomorrow Comment */
.hljs-comment {
color: #969896;
}
/* Tomorrow Red */
.hljs-variable,
.hljs-attribute,
.hljs-tag,
.hljs-regexp,
.ruby .hljs-constant,
.xml .hljs-tag .hljs-title,
.xml .hljs-pi,
.xml .hljs-doctype,
.html .hljs-doctype,
.css .hljs-id,
.css .hljs-class,
.css .hljs-pseudo {
color: #cc6666;
}
/* Tomorrow Orange */
.hljs-number,
.hljs-preprocessor,
.hljs-pragma,
.hljs-built_in,
.hljs-literal,
.hljs-params,
.hljs-constant {
color: #de935f;
}
/* Tomorrow Yellow */
.ruby .hljs-class .hljs-title,
.css .hljs-rule .hljs-attribute {
color: #f0c674;
}
/* Tomorrow Green */
.hljs-string,
.hljs-value,
.hljs-inheritance,
.hljs-header,
.hljs-name,
.ruby .hljs-symbol,
.xml .hljs-cdata {
color: #b5bd68;
}
/* Tomorrow Aqua */
.hljs-title,
.css .hljs-hexcolor {
color: #8abeb7;
}
/* Tomorrow Blue */
.hljs-function,
.python .hljs-decorator,
.python .hljs-title,
.ruby .hljs-function .hljs-title,
.ruby .hljs-title .hljs-keyword,
.perl .hljs-sub,
.javascript .hljs-title,
.coffeescript .hljs-title {
color: #81a2be;
}
/* Tomorrow Purple */
.hljs-keyword,
.javascript .hljs-function {
color: #b294bb;
}
.hljs {
display: block;
overflow-x: auto;
background: #1d1f21;
color: #c5c8c6;
}
.coffeescript .javascript,
.javascript .xml,
.tex .hljs-formula,
.xml .javascript,
.xml .vbscript,
.xml .css,
.xml .hljs-cdata {
opacity: 0.5;
}
.hljs-addition {
color: #718c00;
}
.hljs-deletion {
color: #c82829;
}

9
template/book.toml Normal file
View file

@ -0,0 +1,9 @@
[book]
authors = ["Author Name"]
language = "en"
src = "src"
title = "Book Title"
[output.html]
# Path to a copy of template/theme, relative to this file.
theme = "../../theme"

655
template/theme/book.js Normal file
View file

@ -0,0 +1,655 @@
"use strict";
// Fix back button cache problem
window.onunload = function () { };
// Global variable, shared between modules
function playground_text(playground, hidden = true) {
let code_block = playground.querySelector("code");
if (window.ace && code_block.classList.contains("editable")) {
let editor = window.ace.edit(code_block);
return editor.getValue();
} else if (hidden) {
return code_block.textContent;
} else {
return code_block.innerText;
}
}
(function codeSnippets() {
function fetch_with_timeout(url, options, timeout = 6000) {
return Promise.race([
fetch(url, options),
new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), timeout))
]);
}
var playgrounds = Array.from(document.querySelectorAll(".playground"));
if (playgrounds.length > 0) {
fetch_with_timeout("https://play.rust-lang.org/meta/crates", {
headers: {
'Content-Type': "application/json",
},
method: 'POST',
mode: 'cors',
})
.then(response => response.json())
.then(response => {
// get list of crates available in the rust playground
let playground_crates = response.crates.map(item => item["id"]);
playgrounds.forEach(block => handle_crate_list_update(block, playground_crates));
});
}
function handle_crate_list_update(playground_block, playground_crates) {
// update the play buttons after receiving the response
update_play_button(playground_block, playground_crates);
// and install on change listener to dynamically update ACE editors
if (window.ace) {
let code_block = playground_block.querySelector("code");
if (code_block.classList.contains("editable")) {
let editor = window.ace.edit(code_block);
editor.addEventListener("change", function (e) {
update_play_button(playground_block, playground_crates);
});
// add Ctrl-Enter command to execute rust code
editor.commands.addCommand({
name: "run",
bindKey: {
win: "Ctrl-Enter",
mac: "Ctrl-Enter"
},
exec: _editor => run_rust_code(playground_block)
});
}
}
}
// updates the visibility of play button based on `no_run` class and
// used crates vs ones available on https://play.rust-lang.org
function update_play_button(pre_block, playground_crates) {
var play_button = pre_block.querySelector(".play-button");
// skip if code is `no_run`
if (pre_block.querySelector('code').classList.contains("no_run")) {
play_button.classList.add("hidden");
return;
}
// get list of `extern crate`'s from snippet
var txt = playground_text(pre_block);
var re = /extern\s+crate\s+([a-zA-Z_0-9]+)\s*;/g;
var snippet_crates = [];
var item;
while (item = re.exec(txt)) {
snippet_crates.push(item[1]);
}
// check if all used crates are available on play.rust-lang.org
var all_available = snippet_crates.every(function (elem) {
return playground_crates.indexOf(elem) > -1;
});
if (all_available) {
play_button.classList.remove("hidden");
} else {
play_button.classList.add("hidden");
}
}
function run_rust_code(code_block) {
var result_block = code_block.querySelector(".result");
if (!result_block) {
result_block = document.createElement('code');
result_block.className = 'result hljs language-bash';
code_block.append(result_block);
}
let text = playground_text(code_block);
let classes = code_block.querySelector('code').classList;
let edition = "2015";
if(classes.contains("edition2018")) {
edition = "2018";
} else if(classes.contains("edition2021")) {
edition = "2021";
}
var params = {
version: "stable",
optimize: "0",
code: text,
edition: edition
};
if (text.indexOf("#![feature") !== -1) {
params.version = "nightly";
}
result_block.innerText = "Running...";
fetch_with_timeout("https://play.rust-lang.org/evaluate.json", {
headers: {
'Content-Type': "application/json",
},
method: 'POST',
mode: 'cors',
body: JSON.stringify(params)
})
.then(response => response.json())
.then(response => {
if (response.result.trim() === '') {
result_block.innerText = "No output";
result_block.classList.add("result-no-output");
} else {
result_block.innerText = response.result;
result_block.classList.remove("result-no-output");
}
})
.catch(error => result_block.innerText = "Playground Communication: " + error.message);
}
// Syntax highlighting Configuration
hljs.configure({
tabReplace: ' ', // 4 spaces
languages: [], // Languages used for auto-detection
});
let code_nodes = Array
.from(document.querySelectorAll('code'))
// Don't highlight `inline code` blocks in headers.
.filter(function (node) {return !node.parentElement.classList.contains("header"); });
if (window.ace) {
// language-rust class needs to be removed for editable
// blocks or highlightjs will capture events
code_nodes
.filter(function (node) {return node.classList.contains("editable"); })
.forEach(function (block) { block.classList.remove('language-rust'); });
code_nodes
.filter(function (node) {return !node.classList.contains("editable"); })
.forEach(function (block) { hljs.highlightBlock(block); });
} else {
code_nodes.forEach(function (block) { hljs.highlightBlock(block); });
}
// Adding the hljs class gives code blocks the color css
// even if highlighting doesn't apply
code_nodes.forEach(function (block) { block.classList.add('hljs'); });
Array.from(document.querySelectorAll("code.hljs")).forEach(function (block) {
var lines = Array.from(block.querySelectorAll('.boring'));
// If no lines were hidden, return
if (!lines.length) { return; }
block.classList.add("hide-boring");
var buttons = document.createElement('div');
buttons.className = 'buttons';
buttons.innerHTML = "<button class=\"fa fa-eye\" title=\"Show hidden lines\" aria-label=\"Show hidden lines\"></button>";
// add expand button
var pre_block = block.parentNode;
pre_block.insertBefore(buttons, pre_block.firstChild);
pre_block.querySelector('.buttons').addEventListener('click', function (e) {
if (e.target.classList.contains('fa-eye')) {
e.target.classList.remove('fa-eye');
e.target.classList.add('fa-eye-slash');
e.target.title = 'Hide lines';
e.target.setAttribute('aria-label', e.target.title);
block.classList.remove('hide-boring');
} else if (e.target.classList.contains('fa-eye-slash')) {
e.target.classList.remove('fa-eye-slash');
e.target.classList.add('fa-eye');
e.target.title = 'Show hidden lines';
e.target.setAttribute('aria-label', e.target.title);
block.classList.add('hide-boring');
}
});
});
if (window.playground_copyable) {
Array.from(document.querySelectorAll('pre code')).forEach(function (block) {
var pre_block = block.parentNode;
if (!pre_block.classList.contains('playground')) {
var buttons = pre_block.querySelector(".buttons");
if (!buttons) {
buttons = document.createElement('div');
buttons.className = 'buttons';
pre_block.insertBefore(buttons, pre_block.firstChild);
}
var clipButton = document.createElement('button');
clipButton.className = 'fa fa-copy clip-button';
clipButton.title = 'Copy to clipboard';
clipButton.setAttribute('aria-label', clipButton.title);
clipButton.innerHTML = '<i class=\"tooltiptext\"></i>';
buttons.insertBefore(clipButton, buttons.firstChild);
}
});
}
// Process playground code blocks
Array.from(document.querySelectorAll(".playground")).forEach(function (pre_block) {
// Add play button
var buttons = pre_block.querySelector(".buttons");
if (!buttons) {
buttons = document.createElement('div');
buttons.className = 'buttons';
pre_block.insertBefore(buttons, pre_block.firstChild);
}
var runCodeButton = document.createElement('button');
runCodeButton.className = 'fa fa-play play-button';
runCodeButton.hidden = true;
runCodeButton.title = 'Run this code';
runCodeButton.setAttribute('aria-label', runCodeButton.title);
buttons.insertBefore(runCodeButton, buttons.firstChild);
runCodeButton.addEventListener('click', function (e) {
run_rust_code(pre_block);
});
if (window.playground_copyable) {
var copyCodeClipboardButton = document.createElement('button');
copyCodeClipboardButton.className = 'fa fa-copy clip-button';
copyCodeClipboardButton.innerHTML = '<i class="tooltiptext"></i>';
copyCodeClipboardButton.title = 'Copy to clipboard';
copyCodeClipboardButton.setAttribute('aria-label', copyCodeClipboardButton.title);
buttons.insertBefore(copyCodeClipboardButton, buttons.firstChild);
}
let code_block = pre_block.querySelector("code");
if (window.ace && code_block.classList.contains("editable")) {
var undoChangesButton = document.createElement('button');
undoChangesButton.className = 'fa fa-history reset-button';
undoChangesButton.title = 'Undo changes';
undoChangesButton.setAttribute('aria-label', undoChangesButton.title);
buttons.insertBefore(undoChangesButton, buttons.firstChild);
undoChangesButton.addEventListener('click', function () {
let editor = window.ace.edit(code_block);
editor.setValue(editor.originalCode);
editor.clearSelection();
});
}
});
})();
(function themes() {
var html = document.querySelector('html');
var themeToggleButton = document.getElementById('theme-toggle');
var themePopup = document.getElementById('theme-list');
var themeColorMetaTag = document.querySelector('meta[name="theme-color"]');
var stylesheets = {
ayuHighlight: document.querySelector("[href$='ayu-highlight.css']"),
tomorrowNight: document.querySelector("[href$='tomorrow-night.css']"),
highlight: document.querySelector("[href$='highlight.css']"),
};
function showThemes() {
themePopup.style.display = 'block';
themeToggleButton.setAttribute('aria-expanded', true);
themePopup.querySelector("button#" + get_theme()).focus();
}
function updateThemeSelected() {
themePopup.querySelectorAll('.theme-selected').forEach(function (el) {
el.classList.remove('theme-selected');
});
themePopup.querySelector("button#" + get_theme()).classList.add('theme-selected');
}
function hideThemes() {
themePopup.style.display = 'none';
themeToggleButton.setAttribute('aria-expanded', false);
themeToggleButton.focus();
}
function get_theme() {
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch (e) { }
if (theme === null || theme === undefined) {
return default_theme;
} else {
return theme;
}
}
function set_theme(theme, store = true) {
let ace_theme;
if (theme == 'coal' || theme == 'navy') {
stylesheets.ayuHighlight.disabled = true;
stylesheets.tomorrowNight.disabled = false;
stylesheets.highlight.disabled = true;
ace_theme = "ace/theme/tomorrow_night";
} else if (theme == 'ayu') {
stylesheets.ayuHighlight.disabled = false;
stylesheets.tomorrowNight.disabled = true;
stylesheets.highlight.disabled = true;
ace_theme = "ace/theme/tomorrow_night";
} else {
stylesheets.ayuHighlight.disabled = true;
stylesheets.tomorrowNight.disabled = true;
stylesheets.highlight.disabled = false;
ace_theme = "ace/theme/dawn";
}
setTimeout(function () {
themeColorMetaTag.content = getComputedStyle(document.documentElement).backgroundColor;
}, 1);
if (window.ace && window.editors) {
window.editors.forEach(function (editor) {
editor.setTheme(ace_theme);
});
}
var previousTheme = get_theme();
if (store) {
try { localStorage.setItem('mdbook-theme', theme); } catch (e) { }
}
html.classList.remove(previousTheme);
html.classList.add(theme);
updateThemeSelected();
}
// Set theme
var theme = get_theme();
set_theme(theme, false);
themeToggleButton.addEventListener('click', function () {
if (themePopup.style.display === 'block') {
hideThemes();
} else {
showThemes();
}
});
themePopup.addEventListener('click', function (e) {
var theme;
if (e.target.className === "theme") {
theme = e.target.id;
} else if (e.target.parentElement.className === "theme") {
theme = e.target.parentElement.id;
} else {
return;
}
set_theme(theme);
});
themePopup.addEventListener('focusout', function(e) {
// e.relatedTarget is null in Safari and Firefox on macOS (see workaround below)
if (!!e.relatedTarget && !themeToggleButton.contains(e.relatedTarget) && !themePopup.contains(e.relatedTarget)) {
hideThemes();
}
});
// Should not be needed, but it works around an issue on macOS & iOS: https://github.com/rust-lang/mdBook/issues/628
document.addEventListener('click', function(e) {
if (themePopup.style.display === 'block' && !themeToggleButton.contains(e.target) && !themePopup.contains(e.target)) {
hideThemes();
}
});
document.addEventListener('keydown', function (e) {
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
if (!themePopup.contains(e.target)) { return; }
switch (e.key) {
case 'Escape':
e.preventDefault();
hideThemes();
break;
case 'ArrowUp':
e.preventDefault();
var li = document.activeElement.parentElement;
if (li && li.previousElementSibling) {
li.previousElementSibling.querySelector('button').focus();
}
break;
case 'ArrowDown':
e.preventDefault();
var li = document.activeElement.parentElement;
if (li && li.nextElementSibling) {
li.nextElementSibling.querySelector('button').focus();
}
break;
case 'Home':
e.preventDefault();
themePopup.querySelector('li:first-child button').focus();
break;
case 'End':
e.preventDefault();
themePopup.querySelector('li:last-child button').focus();
break;
}
});
})();
(function sidebar() {
var body = document.querySelector("body");
var sidebar = document.getElementById("sidebar");
var sidebarLinks = document.querySelectorAll('#sidebar a');
var sidebarToggleButton = document.getElementById("sidebar-toggle");
var sidebarResizeHandle = document.getElementById("sidebar-resize-handle");
var firstContact = null;
function showSidebar() {
body.classList.remove('sidebar-hidden')
body.classList.add('sidebar-visible');
Array.from(sidebarLinks).forEach(function (link) {
link.setAttribute('tabIndex', 0);
});
sidebarToggleButton.setAttribute('aria-expanded', true);
sidebar.setAttribute('aria-hidden', false);
try { localStorage.setItem('mdbook-sidebar', 'visible'); } catch (e) { }
}
var sidebarAnchorToggles = document.querySelectorAll('#sidebar a.toggle');
function toggleSection(ev) {
ev.currentTarget.parentElement.classList.toggle('expanded');
}
Array.from(sidebarAnchorToggles).forEach(function (el) {
el.addEventListener('click', toggleSection);
});
function hideSidebar() {
body.classList.remove('sidebar-visible')
body.classList.add('sidebar-hidden');
Array.from(sidebarLinks).forEach(function (link) {
link.setAttribute('tabIndex', -1);
});
sidebarToggleButton.setAttribute('aria-expanded', false);
sidebar.setAttribute('aria-hidden', true);
try { localStorage.setItem('mdbook-sidebar', 'hidden'); } catch (e) { }
}
// Toggle sidebar
sidebarToggleButton.addEventListener('click', function sidebarToggle() {
if (body.classList.contains("sidebar-hidden")) {
var current_width = parseInt(
document.documentElement.style.getPropertyValue('--sidebar-width'), 10);
if (current_width < 150) {
document.documentElement.style.setProperty('--sidebar-width', '150px');
}
showSidebar();
} else if (body.classList.contains("sidebar-visible")) {
hideSidebar();
} else {
if (getComputedStyle(sidebar)['transform'] === 'none') {
hideSidebar();
} else {
showSidebar();
}
}
});
sidebarResizeHandle.addEventListener('mousedown', initResize, false);
function initResize(e) {
window.addEventListener('mousemove', resize, false);
window.addEventListener('mouseup', stopResize, false);
body.classList.add('sidebar-resizing');
}
function resize(e) {
var viewportOffset = sidebar.getBoundingClientRect();
var pos = (e.clientX - sidebar.offsetLeft - viewportOffset.left);
if (pos < 20) {
hideSidebar();
} else {
if (body.classList.contains("sidebar-hidden")) {
showSidebar();
}
pos = Math.min(pos, window.innerWidth - 100);
document.documentElement.style.setProperty('--sidebar-width', pos + 'px');
}
}
//on mouseup remove windows functions mousemove & mouseup
function stopResize(e) {
body.classList.remove('sidebar-resizing');
window.removeEventListener('mousemove', resize, false);
window.removeEventListener('mouseup', stopResize, false);
}
document.addEventListener('touchstart', function (e) {
firstContact = {
x: e.touches[0].clientX,
time: Date.now()
};
}, { passive: true });
document.addEventListener('touchmove', function (e) {
if (!firstContact)
return;
var curX = e.touches[0].clientX;
var xDiff = curX - firstContact.x,
tDiff = Date.now() - firstContact.time;
if (tDiff < 250 && Math.abs(xDiff) >= 150) {
if (xDiff >= 0 && firstContact.x < Math.min(document.body.clientWidth * 0.25, 300))
showSidebar();
else if (xDiff < 0 && curX < 300)
hideSidebar();
firstContact = null;
}
}, { passive: true });
})();
(function chapterNavigation() {
document.addEventListener('keydown', function (e) {
if (e.altKey || e.ctrlKey || e.metaKey || e.shiftKey) { return; }
if (window.search && window.search.hasFocus()) { return; }
var html = document.querySelector('html');
function next() {
var nextButton = document.querySelector('.nav-chapters.next');
if (nextButton) {
window.location.href = nextButton.href;
}
}
function prev() {
var previousButton = document.querySelector('.nav-chapters.previous');
if (previousButton) {
window.location.href = previousButton.href;
}
}
switch (e.key) {
case 'ArrowRight':
e.preventDefault();
if (html.dir == 'rtl') {
prev();
} else {
next();
}
break;
case 'ArrowLeft':
e.preventDefault();
if (html.dir == 'rtl') {
next();
} else {
prev();
}
break;
}
});
})();
(function clipboard() {
var clipButtons = document.querySelectorAll('.clip-button');
function hideTooltip(elem) {
elem.firstChild.innerText = "";
elem.className = 'fa fa-copy clip-button';
}
function showTooltip(elem, msg) {
elem.firstChild.innerText = msg;
elem.className = 'fa fa-copy tooltipped';
}
var clipboardSnippets = new ClipboardJS('.clip-button', {
text: function (trigger) {
hideTooltip(trigger);
let playground = trigger.closest("pre");
return playground_text(playground, false);
}
});
Array.from(clipButtons).forEach(function (clipButton) {
clipButton.addEventListener('mouseout', function (e) {
hideTooltip(e.currentTarget);
});
});
clipboardSnippets.on('success', function (e) {
e.clearSelection();
showTooltip(e.trigger, "Copied!");
});
clipboardSnippets.on('error', function (e) {
showTooltip(e.trigger, "Clipboard error!");
});
})();
(function scrollToTop () {
var menuTitle = document.querySelector('.menu-title');
menuTitle.addEventListener('click', function () {
document.scrollingElement.scrollTo({ top: 0, behavior: 'smooth' });
});
})();
(function controllMenu() {
var menu = document.getElementById('menu-bar');
(function controllBorder() {
function updateBorder() {
if (menu.offsetTop === 0) {
menu.classList.remove('bordered');
} else {
menu.classList.add('bordered');
}
}
updateBorder();
document.addEventListener('scroll', updateBorder, { passive: true });
})();
})();

View file

@ -0,0 +1,82 @@
/*
* An increased contrast highlighting scheme loosely based on the
* "Base16 Atelier Dune Light" theme by Bram de Haan
* (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
* Original Base16 color scheme by Chris Kempson
* (https://github.com/chriskempson/base16)
*/
/* Comment */
.hljs-comment,
.hljs-quote {
color: #575757;
}
/* Red */
.hljs-variable,
.hljs-template-variable,
.hljs-attribute,
.hljs-tag,
.hljs-name,
.hljs-regexp,
.hljs-link,
.hljs-name,
.hljs-selector-id,
.hljs-selector-class {
color: #d70025;
}
/* Orange */
.hljs-number,
.hljs-meta,
.hljs-built_in,
.hljs-builtin-name,
.hljs-literal,
.hljs-type,
.hljs-params {
color: #b21e00;
}
/* Green */
.hljs-string,
.hljs-symbol,
.hljs-bullet {
color: #008200;
}
/* Blue */
.hljs-title,
.hljs-section {
color: #0030f2;
}
/* Purple */
.hljs-keyword,
.hljs-selector-tag {
color: #9d00ec;
}
.hljs {
display: block;
overflow-x: auto;
background: #f6f7f6;
color: #000;
}
.hljs-emphasis {
font-style: italic;
}
.hljs-strong {
font-weight: bold;
}
.hljs-addition {
color: #22863a;
background-color: #f0fff4;
}
.hljs-deletion {
color: #b31d28;
background-color: #ffeef0;
}

File diff suppressed because one or more lines are too long

292
template/theme/index.hbs Normal file
View file

@ -0,0 +1,292 @@
<!-- Lang: {{ language }} -->
<!-- Title: {{ title }} -->
<!-- Print: {{#if print_enable}}enabled{{else}}disabled{{/if}} -->
<!-- MathJax: {{#if mathjax_support}}supported{{else}}unsupported{{/if}} -->
<!-- mdBook -->
<!-- Provide site root to javascript -->
<script>
var path_to_root = "{{ path_to_root }}";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "{{ preferred_dark_theme }}" : "{{ default_theme }}";
</script>
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('{{ default_theme }}')
html.classList.add(theme);
var body = document.querySelector('body');
body.classList.remove('no-js')
body.classList.add('js');
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var body = document.querySelector('body');
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
body.classList.remove('sidebar-visible');
body.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<div class="sidebar-scrollbox">
{{#toc}}{{/toc}}
</div>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<!-- Track and set sidebar scroll position -->
<script>
var sidebarScrollbox = document.querySelector('#sidebar .sidebar-scrollbox');
sidebarScrollbox.addEventListener('click', function(e) {
if (e.target.tagName === 'A') {
sessionStorage.setItem('sidebar-scroll', sidebarScrollbox.scrollTop);
}
}, { passive: true });
var sidebarScrollTop = sessionStorage.getItem('sidebar-scroll');
sessionStorage.removeItem('sidebar-scroll');
if (sidebarScrollTop) {
// preserve sidebar scroll position when navigating via links within sidebar
sidebarScrollbox.scrollTop = sidebarScrollTop;
} else {
// scroll sidebar to current active section when navigating via "next/previous chapter" buttons
var activeSection = document.querySelector('#sidebar .active');
if (activeSection) {
activeSection.scrollIntoView({ block: 'center' });
}
}
</script>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
{{> header}}
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
{{#if search_enabled}}
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
{{/if}}
</div>
<h1 class="menu-title">{{ book_title }}</h1>
<div class="right-buttons">
{{#if print_enable}}
<a href="{{ path_to_root }}print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
{{/if}}
{{#if git_repository_url}}
<a href="{{git_repository_url}}" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa {{git_repository_icon}}"></i>
</a>
{{/if}}
{{#if git_repository_edit_url}}
<a href="{{git_repository_edit_url}}" title="Suggest an edit" aria-label="Suggest an edit">
<i id="git-edit-button" class="fa fa-edit"></i>
</a>
{{/if}}
</div>
</div>
{{#if search_enabled}}
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
{{/if}}
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
{{{ content }}}
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
{{#previous}}
<a rel="prev" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
{{/previous}}
{{#next}}
<a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
{{/next}}
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
{{#previous}}
<a rel="prev" href="{{ path_to_root }}{{link}}" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
{{/previous}}
{{#next}}
<a rel="next prefetch" href="{{ path_to_root }}{{link}}" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
{{/next}}
</nav>
</div>
{{#if live_reload_endpoint}}
<!-- Livereload script (if served using the cli tool) -->
<script>
const wsProtocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsAddress = wsProtocol + "//" + location.host + "/" + "{{{live_reload_endpoint}}}";
const socket = new WebSocket(wsAddress);
socket.onmessage = function (event) {
if (event.data === "reload") {
socket.close();
location.reload();
}
};
window.onbeforeunload = function() {
socket.close();
}
</script>
{{/if}}
{{#if google_analytics}}
<!-- Google Analytics Tag -->
<script>
var localAddrs = ["localhost", "127.0.0.1", ""];
// make sure we don't activate google analytics if the developer is
// inspecting the book locally...
if (localAddrs.indexOf(document.location.hostname) === -1) {
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
ga('create', '{{google_analytics}}', 'auto');
ga('send', 'pageview');
}
</script>
{{/if}}
{{#if playground_line_numbers}}
<script>
window.playground_line_numbers = true;
</script>
{{/if}}
{{#if playground_copyable}}
<script>
window.playground_copyable = true;
</script>
{{/if}}
{{#if playground_js}}
<script src="{{ path_to_root }}ace.js"></script>
<script src="{{ path_to_root }}editor.js"></script>
<script src="{{ path_to_root }}mode-rust.js"></script>
<script src="{{ path_to_root }}theme-dawn.js"></script>
<script src="{{ path_to_root }}theme-tomorrow_night.js"></script>
{{/if}}
{{#if search_js}}
<script src="{{ path_to_root }}elasticlunr.min.js"></script>
<script src="{{ path_to_root }}mark.min.js"></script>
<script src="{{ path_to_root }}searcher.js"></script>
{{/if}}
<script src="{{ path_to_root }}clipboard.min.js"></script>
<script src="{{ path_to_root }}highlight.js"></script>
<script src="{{ path_to_root }}book.js"></script>
<!-- Custom JS scripts -->
{{#each additional_js}}
<script src="{{ ../path_to_root }}{{this}}"></script>
{{/each}}
{{#if is_print}}
{{#if mathjax_support}}
<script>
window.addEventListener('load', function() {
MathJax.Hub.Register.StartupHook('End', function() {
window.setTimeout(window.print, 100);
});
});
</script>
{{else}}
<script>
window.addEventListener('load', function() {
window.setTimeout(window.print, 100);
});
</script>
{{/if}}
{{/if}}