Merge pull request #1221 from manuel-woelker/fb-539-not-found-page

Generate 404.html page (#539)
This commit is contained in:
Eric Huss 2020-06-23 10:48:08 -07:00 committed by GitHub
commit 9268884b17
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 137 additions and 4 deletions

View File

@ -9,6 +9,7 @@ edition = "2018"
[output.html]
mathjax-support = true
site-url = "/mdBook/"
[output.html.playground]
editable = true

3
book-example/src/404.md Normal file
View File

@ -0,0 +1,3 @@
# Document not found (404)
This URL is invalid, sorry. Try the search instead!

View File

@ -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

View File

@ -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::<Message>(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<Message>) {
async fn serve(
build_dir: PathBuf,
address: SocketAddr,
reload_tx: broadcast::Sender<Message>,
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;
}

View File

@ -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<String>,
/// Input path for the 404 file, defaults to 404.md, set to "" to disable 404 file output
pub input_404: Option<String>,
/// 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<String>,
/// 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");
}
}

View File

@ -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<String, serde_json::Value>,
) -> 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 {

View File

@ -7,6 +7,10 @@
{{#if is_print }}
<meta name="robots" content="noindex" />
{{/if}}
{{#if base_url}}
<base href="{{ base_url }}">
{{/if}}
<!-- Custom HTML head -->
{{> head}}

View File

@ -177,6 +177,13 @@ pub fn copy_files_except_ext(
Ok(())
}
pub fn get_404_output_file(input_404: &Option<String>) -> String {
input_404
.as_ref()
.unwrap_or(&"404.md".to_string())
.replace(".md", ".html")
}
#[cfg(test)]
mod tests {
use super::copy_files_except_ext;