diff --git a/book-example/book.toml b/book-example/book.toml index da7d23f3..96dcf312 100644 --- a/book-example/book.toml +++ b/book-example/book.toml @@ -9,6 +9,7 @@ edition = "2018" [output.html] mathjax-support = true +site-url = "/mdBook/" [output.html.playground] editable = true diff --git a/book-example/src/404.md b/book-example/src/404.md new file mode 100644 index 00000000..a55db44e --- /dev/null +++ b/book-example/src/404.md @@ -0,0 +1,3 @@ +# Document not found (404) + +This URL is invalid, sorry. Try the search instead! \ No newline at end of file diff --git a/book-example/src/format/config.md b/book-example/src/format/config.md index 42245eb3..c7878f93 100644 --- a/book-example/src/format/config.md +++ b/book-example/src/format/config.md @@ -204,6 +204,12 @@ The following configuration options are available: `/appendices/bibliography.html`). The value can be any valid URI the browser should navigate to (e.g. `https://rust-lang.org/`, `/overview.html`, or `../bibliography.html`). +- **input-404:** The name of the markdown file used for misssing files. + The corresponding output file will be the same, with the extension replaced with `html`. + Defaults to `404.md`. +- **site-url:** The url where the book will be hosted. This is required to ensure + navigation links and script/css imports in the 404 file work correctly, even when accessing + urls in subdirectories. Defaults to `/`. Available configuration options for the `[output.html.fold]` table: @@ -266,6 +272,8 @@ additional-js = ["custom.js"] no-section-label = false git-repository-url = "https://github.com/rust-lang/mdBook" git-repository-icon = "fa-github" +site-url = "/example-book/" +input-404 = "not-found.md" [output.html.fold] enable = false diff --git a/src/cmd/serve.rs b/src/cmd/serve.rs index 4e865f61..0940938f 100644 --- a/src/cmd/serve.rs +++ b/src/cmd/serve.rs @@ -6,6 +6,7 @@ use futures_util::sink::SinkExt; use futures_util::StreamExt; use mdbook::errors::*; use mdbook::utils; +use mdbook::utils::fs::get_404_output_file; use mdbook::MDBook; use std::net::{SocketAddr, ToSocketAddrs}; use std::path::PathBuf; @@ -68,6 +69,8 @@ pub fn execute(args: &ArgMatches) -> Result<()> { if let Some(dest_dir) = args.value_of("dest-dir") { book.config.build.build_dir = dest_dir.into(); } + // Override site-url for local serving of the 404 file + book.config.set("output.html.site-url", "/")?; book.build()?; @@ -76,13 +79,20 @@ pub fn execute(args: &ArgMatches) -> Result<()> { .next() .ok_or_else(|| anyhow::anyhow!("no address found for {}", address))?; let build_dir = book.build_dir_for("html"); + let input_404 = book + .config + .get("output.html.input-404") + .map(toml::Value::as_str) + .and_then(std::convert::identity) // flatten + .map(ToString::to_string); + let file_404 = get_404_output_file(&input_404); // A channel used to broadcast to any websockets to reload when a file changes. let (tx, _rx) = tokio::sync::broadcast::channel::(100); let reload_tx = tx.clone(); let thread_handle = std::thread::spawn(move || { - serve(build_dir, sockaddr, reload_tx); + serve(build_dir, sockaddr, reload_tx, &file_404); }); let serving_url = format!("http://{}", address); @@ -120,7 +130,12 @@ pub fn execute(args: &ArgMatches) -> Result<()> { } #[tokio::main] -async fn serve(build_dir: PathBuf, address: SocketAddr, reload_tx: broadcast::Sender) { +async fn serve( + build_dir: PathBuf, + address: SocketAddr, + reload_tx: broadcast::Sender, + file_404: &str, +) { // A warp Filter which captures `reload_tx` and provides an `rx` copy to // receive reload messages. let sender = warp::any().map(move || reload_tx.subscribe()); @@ -142,7 +157,10 @@ async fn serve(build_dir: PathBuf, address: SocketAddr, reload_tx: broadcast::Se }) }); // A warp Filter that serves from the filesystem. - let book_route = warp::fs::dir(build_dir); - let routes = livereload.or(book_route); + let book_route = warp::fs::dir(build_dir.clone()); + // The fallback route for 404 errors + let fallback_route = warp::fs::file(build_dir.join(file_404)) + .map(|reply| warp::reply::with_status(reply, warp::http::StatusCode::NOT_FOUND)); + let routes = livereload.or(book_route).or(fallback_route); warp::serve(routes).run(address).await; } diff --git a/src/config.rs b/src/config.rs index 8496370c..1389f139 100644 --- a/src/config.rs +++ b/src/config.rs @@ -504,6 +504,10 @@ pub struct HtmlConfig { /// FontAwesome icon class to use for the Git repository link. /// Defaults to `fa-github` if `None`. pub git_repository_icon: Option, + /// Input path for the 404 file, defaults to 404.md, set to "" to disable 404 file output + pub input_404: Option, + /// Absolute url to site, used to emit correct paths for the 404 page, which might be accessed in a deeply nested directory + pub site_url: Option, /// This is used as a bit of a workaround for the `mdbook serve` command. /// Basically, because you set the websocket port from the command line, the /// `mdbook serve` command needs a way to let the HTML renderer know where @@ -535,6 +539,8 @@ impl Default for HtmlConfig { search: None, git_repository_url: None, git_repository_icon: None, + input_404: None, + site_url: None, livereload_url: None, redirect: HashMap::new(), } @@ -667,6 +673,7 @@ impl<'de, T> Updateable<'de> for T where T: Serialize + Deserialize<'de> {} #[cfg(test)] mod tests { use super::*; + use crate::utils::fs::get_404_output_file; const COMPLEX_CONFIG: &str = r#" [book] @@ -1001,4 +1008,31 @@ mod tests { assert_eq!(cfg.book.title, Some(should_be)); } + + #[test] + fn file_404_default() { + let src = r#" + [output.html] + destination = "my-book" + "#; + + let got = Config::from_str(src).unwrap(); + let html_config = got.html_config().unwrap(); + assert_eq!(html_config.input_404, None); + assert_eq!(&get_404_output_file(&html_config.input_404), "404.html"); + } + + #[test] + fn file_404_custom() { + let src = r#" + [output.html] + input-404= "missing.md" + output-404= "missing.html" + "#; + + let got = Config::from_str(src).unwrap(); + let html_config = got.html_config().unwrap(); + assert_eq!(html_config.input_404, Some("missing.md".to_string())); + assert_eq!(&get_404_output_file(&html_config.input_404), "missing.html"); + } } diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs index e5544291..24c780e2 100644 --- a/src/renderer/html_handlebars/hbs_renderer.rs +++ b/src/renderer/html_handlebars/hbs_renderer.rs @@ -12,6 +12,7 @@ use std::collections::HashMap; use std::fs::{self, File}; use std::path::{Path, PathBuf}; +use crate::utils::fs::get_404_output_file; use handlebars::Handlebars; use regex::{Captures, Regex}; @@ -105,6 +106,58 @@ impl HtmlHandlebars { Ok(()) } + fn render_404( + &self, + ctx: &RenderContext, + html_config: &HtmlConfig, + src_dir: &PathBuf, + handlebars: &mut Handlebars<'_>, + data: &mut serde_json::Map, + ) -> Result<()> { + let destination = &ctx.destination; + let content_404 = if let Some(ref filename) = html_config.input_404 { + let path = src_dir.join(filename); + std::fs::read_to_string(&path) + .with_context(|| format!("unable to open 404 input file {:?}", path))? + } else { + // 404 input not explicitly configured try the default file 404.md + let default_404_location = src_dir.join("404.md"); + if default_404_location.exists() { + std::fs::read_to_string(&default_404_location).with_context(|| { + format!("unable to open 404 input file {:?}", default_404_location) + })? + } else { + "# Document not found (404)\n\nThis URL is invalid, sorry. Please use the \ + navigation bar or search to continue." + .to_string() + } + }; + let html_content_404 = utils::render_markdown(&content_404, html_config.curly_quotes); + + let mut data_404 = data.clone(); + let base_url = if let Some(site_url) = &html_config.site_url { + site_url + } else { + debug!( + "HTML 'site-url' parameter not set, defaulting to '/'. Please configure \ + this to ensure the 404 page work correctly, especially if your site is hosted in a \ + subdirectory on the HTTP server." + ); + "/" + }; + data_404.insert("base_url".to_owned(), json!(base_url)); + // Set a dummy path to ensure other paths (e.g. in the TOC) are generated correctly + data_404.insert("path".to_owned(), json!("404.md")); + data_404.insert("content".to_owned(), json!(html_content_404)); + let rendered = handlebars.render("index", &data_404)?; + + let rendered = self.post_process(rendered, &html_config.playpen, ctx.config.rust.edition); + let output_file = get_404_output_file(&html_config.input_404); + utils::fs::write_file(&destination, output_file, rendered.as_bytes())?; + debug!("Creating 404.html ✓"); + Ok(()) + } + #[cfg_attr(feature = "cargo-clippy", allow(clippy::let_and_return))] fn post_process( &self, @@ -441,6 +494,11 @@ impl Renderer for HtmlHandlebars { is_index = false; } + // Render 404 page + if html_config.input_404 != Some("".to_string()) { + self.render_404(ctx, &html_config, &src_dir, &mut handlebars, &mut data)?; + } + // Print version self.configure_print_version(&mut data, &print_content); if let Some(ref title) = ctx.config.book.title { diff --git a/src/theme/index.hbs b/src/theme/index.hbs index 3d2222f4..329318c4 100644 --- a/src/theme/index.hbs +++ b/src/theme/index.hbs @@ -7,6 +7,10 @@ {{#if is_print }} {{/if}} + {{#if base_url}} + + {{/if}} + {{> head}} diff --git a/src/utils/fs.rs b/src/utils/fs.rs index d4c0cb5f..7a7aa63a 100644 --- a/src/utils/fs.rs +++ b/src/utils/fs.rs @@ -177,6 +177,13 @@ pub fn copy_files_except_ext( Ok(()) } +pub fn get_404_output_file(input_404: &Option) -> String { + input_404 + .as_ref() + .unwrap_or(&"404.md".to_string()) + .replace(".md", ".html") +} + #[cfg(test)] mod tests { use super::copy_files_except_ext;