Move error types to mdbook-core

ehuss · ehuss · commit f51d89ba02cd · 2025-07-23T17:29:55.000-07:00
This moves Result and Error to mdbook-core with the anticipation of
using them in user crates. For now, the internal APIs will be using
anyhow directly, but the intent is to transition more of these to
mdbook-core where it makes sense.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -21,6 +21,7 @@ repository = "https://github.com/rust-lang/mdBook"
 rust-version = "1.85.0" # Keep in sync with installation.md and .github/workflows/main.yml
 
 [workspace.dependencies]
+anyhow = "1.0.98"
 mdbook-core = { path = "crates/mdbook-core" }
 
 [package]
@@ -42,7 +43,7 @@ description = "Creates a book from markdown files"
 rust-version.workspace = true
 
 [dependencies]
-anyhow = "1.0.71"
+anyhow.workspace = true
 chrono = { version = "0.4.24", default-features = false, features = ["clock"] }
 clap = { version = "4.3.12", features = ["cargo", "wrap_help"] }
 clap_complete = "4.3.2"
diff --git a/crates/mdbook-core/Cargo.toml b/crates/mdbook-core/Cargo.toml
@@ -8,6 +8,7 @@ repository.workspace = true
 rust-version.workspace = true
 
 [dependencies]
+anyhow.workspace = true
 
 [lints]
 workspace = true
diff --git a/crates/mdbook-core/src/lib.rs b/crates/mdbook-core/src/lib.rs
@@ -5,3 +5,8 @@
 /// This is provided as a way for custom preprocessors and renderers to do
 /// compatibility checks.
 pub const MDBOOK_VERSION: &str = env!("CARGO_PKG_VERSION");
+
+/// The error types used in mdbook.
+pub mod errors {
+    pub use anyhow::{Error, Result};
+}
diff --git a/examples/nop-preprocessor.rs b/examples/nop-preprocessor.rs
@@ -1,9 +1,9 @@
 //! A basic example of a preprocessor that does nothing.
 
 use crate::nop_lib::Nop;
+use anyhow::Error;
 use clap::{Arg, ArgMatches, Command};
 use mdbook::book::Book;
-use mdbook::errors::Error;
 use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
 use semver::{Version, VersionReq};
 use std::io;
diff --git a/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml b/examples/remove-emphasis/mdbook-remove-emphasis/Cargo.toml
@@ -4,6 +4,7 @@ version = "0.1.0"
 edition.workspace = true
 
 [dependencies]
+anyhow.workspace = true
 mdbook = { path = "../../.." }
 pulldown-cmark = { version = "0.12.2", default-features = false }
 pulldown-cmark-to-cmark = "18.0.0"
diff --git a/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs b/examples/remove-emphasis/mdbook-remove-emphasis/src/main.rs
@@ -1,9 +1,9 @@
 //! This is a demonstration of an mdBook preprocessor which parses markdown
 //! and removes any instances of emphasis.
 
+use anyhow::Error;
 use mdbook::BookItem;
 use mdbook::book::{Book, Chapter};
-use mdbook::errors::Error;
 use mdbook::preprocess::{CmdPreprocessor, Preprocessor, PreprocessorContext};
 use pulldown_cmark::{Event, Parser, Tag, TagEnd};
 use std::io;
diff --git a/src/book/book.rs b/src/book/book.rs
@@ -6,8 +6,8 @@ use std::path::{Path, PathBuf};
 
 use super::summary::{Link, SectionNumber, Summary, SummaryItem, parse_summary};
 use crate::config::BuildConfig;
-use crate::errors::*;
 use crate::utils::bracket_escape;
+use anyhow::{Context, Result};
 use log::debug;
 use serde::{Deserialize, Serialize};
 
diff --git a/src/book/init.rs b/src/book/init.rs
@@ -4,9 +4,9 @@ use std::path::PathBuf;
 
 use super::MDBook;
 use crate::config::Config;
-use crate::errors::*;
 use crate::theme;
 use crate::utils::fs::write_file;
+use anyhow::{Context, Result};
 use log::{debug, error, info, trace};
 
 /// A helper for setting up a new book and its directory structure.
diff --git a/src/book/mod.rs b/src/book/mod.rs
@@ -13,6 +13,7 @@ pub use self::book::{Book, BookItem, BookItems, Chapter, load_book};
 pub use self::init::BookBuilder;
 pub use self::summary::{Link, SectionNumber, Summary, SummaryItem, parse_summary};
 
+use anyhow::{Context, Error, Result, bail};
 use log::{debug, error, info, log_enabled, trace, warn};
 use std::ffi::OsString;
 use std::io::{IsTerminal, Write};
@@ -22,7 +23,6 @@ use tempfile::Builder as TempFileBuilder;
 use toml::Value;
 use topological_sort::TopologicalSort;
 
-use crate::errors::*;
 use crate::preprocess::{
     CmdPreprocessor, IndexPreprocessor, LinkPreprocessor, Preprocessor, PreprocessorContext,
 };
diff --git a/src/book/summary.rs b/src/book/summary.rs
@@ -1,4 +1,4 @@
-use crate::errors::*;
+use anyhow::{Context, Error, Result, bail};
 use log::{debug, trace, warn};
 use memchr::Memchr;
 use pulldown_cmark::{DefaultBrokenLinkCallback, Event, HeadingLevel, Tag, TagEnd};
diff --git a/src/cmd/build.rs b/src/cmd/build.rs
@@ -1,7 +1,7 @@
 use super::command_prelude::*;
 use crate::{get_book_dir, open};
+use anyhow::Result;
 use mdbook::MDBook;
-use mdbook::errors::Result;
 use std::path::PathBuf;
 
 // Create clap subcommand arguments
diff --git a/src/cmd/clean.rs b/src/cmd/clean.rs
@@ -1,6 +1,7 @@
 use super::command_prelude::*;
 use crate::get_book_dir;
 use anyhow::Context;
+use anyhow::Result;
 use mdbook::MDBook;
 use std::mem::take;
 use std::path::PathBuf;
@@ -15,7 +16,7 @@ pub fn make_subcommand() -> Command {
 }
 
 // Clean command implementation
-pub fn execute(args: &ArgMatches) -> mdbook::errors::Result<()> {
+pub fn execute(args: &ArgMatches) -> Result<()> {
     let book_dir = get_book_dir(args);
     let book = MDBook::load(book_dir)?;
 
@@ -47,7 +48,7 @@ pub struct Clean {
 }
 
 impl Clean {
-    fn new(dir: &PathBuf) -> mdbook::errors::Result<Clean> {
+    fn new(dir: &PathBuf) -> Result<Clean> {
         let mut files = vec![dir.clone()];
         let mut children = Vec::new();
         let mut num_files_removed = 0;
diff --git a/src/cmd/init.rs b/src/cmd/init.rs
@@ -1,8 +1,8 @@
 use crate::get_book_dir;
+use anyhow::Result;
 use clap::{ArgMatches, Command as ClapCommand, arg};
 use mdbook::MDBook;
 use mdbook::config;
-use mdbook::errors::Result;
 use std::io;
 use std::io::Write;
 use std::process::Command;
diff --git a/src/cmd/serve.rs b/src/cmd/serve.rs
@@ -2,14 +2,14 @@ use super::command_prelude::*;
 #[cfg(feature = "watch")]
 use super::watch;
 use crate::{get_book_dir, open};
+use anyhow::Result;
 use axum::Router;
 use axum::extract::ws::{Message, WebSocket, WebSocketUpgrade};
 use axum::routing::get;
 use clap::builder::NonEmptyStringValueParser;
 use futures_util::StreamExt;
 use futures_util::sink::SinkExt;
 use mdbook::MDBook;
-use mdbook::errors::*;
 use mdbook::utils::fs::get_404_output_file;
 use std::net::{SocketAddr, ToSocketAddrs};
 use std::path::PathBuf;
diff --git a/src/cmd/test.rs b/src/cmd/test.rs
@@ -1,9 +1,9 @@
 use super::command_prelude::*;
 use crate::get_book_dir;
+use anyhow::Result;
 use clap::ArgAction;
 use clap::builder::NonEmptyStringValueParser;
 use mdbook::MDBook;
-use mdbook::errors::Result;
 use std::path::PathBuf;
 
 // Create clap subcommand arguments
diff --git a/src/cmd/watch.rs b/src/cmd/watch.rs
@@ -1,7 +1,7 @@
 use super::command_prelude::*;
 use crate::{get_book_dir, open};
+use anyhow::Result;
 use mdbook::MDBook;
-use mdbook::errors::Result;
 use std::path::{Path, PathBuf};
 
 mod native;
diff --git a/src/config.rs b/src/config.rs
@@ -9,7 +9,7 @@
 //! # Examples
 //!
 //! ```rust
-//! # use mdbook::errors::*;
+//! # use anyhow::Result;
 //! use std::path::PathBuf;
 //! use std::str::FromStr;
 //! use mdbook::Config;
@@ -47,6 +47,8 @@
 //! # run().unwrap()
 //! ```
 
+use crate::utils::{self, toml_ext::TomlExt};
+use anyhow::{Context, Error, Result, bail};
 use log::{debug, trace, warn};
 use serde::{Deserialize, Deserializer, Serialize, Serializer};
 use std::collections::HashMap;
@@ -58,9 +60,6 @@ use std::str::FromStr;
 use toml::Value;
 use toml::value::Table;
 
-use crate::errors::*;
-use crate::utils::{self, toml_ext::TomlExt};
-
 /// The overall configuration object for MDBook, essentially an in-memory
 /// representation of `book.toml`.
 #[derive(Debug, Clone, PartialEq)]
diff --git a/src/front-end/mod.rs b/src/front-end/mod.rs
@@ -1,18 +1,16 @@
 #![allow(missing_docs)]
 
-pub mod playground_editor;
+use anyhow::Result;
+use log::warn;
+use std::fs::File;
+use std::io::Read;
+use std::path::{Path, PathBuf};
 
 pub mod fonts;
-
+pub mod playground_editor;
 #[cfg(feature = "search")]
 pub mod searcher;
 
-use std::fs::File;
-use std::io::Read;
-use std::path::{Path, PathBuf};
-
-use crate::errors::*;
-use log::warn;
 pub static INDEX: &[u8] = include_bytes!("templates/index.hbs");
 pub static HEAD: &[u8] = include_bytes!("templates/head.hbs");
 pub static REDIRECT: &[u8] = include_bytes!("templates/redirect.hbs");
diff --git a/src/lib.rs b/src/lib.rs
@@ -93,9 +93,3 @@ pub use crate::book::MDBook;
 pub use crate::config::Config;
 pub use crate::renderer::Renderer;
 pub use mdbook_core::MDBOOK_VERSION;
-
-/// The error types used through out this crate.
-pub mod errors {
-    pub(crate) use anyhow::{Context, bail, ensure};
-    pub use anyhow::{Error, Result};
-}
diff --git a/src/preprocess/cmd.rs b/src/preprocess/cmd.rs
@@ -1,6 +1,6 @@
 use super::{Preprocessor, PreprocessorContext};
 use crate::book::Book;
-use crate::errors::*;
+use anyhow::{Context, Result, bail, ensure};
 use log::{debug, trace, warn};
 use shlex::Shlex;
 use std::io::{self, Read, Write};
diff --git a/src/preprocess/index.rs b/src/preprocess/index.rs
@@ -3,7 +3,7 @@ use std::{path::Path, sync::LazyLock};
 
 use super::{Preprocessor, PreprocessorContext};
 use crate::book::{Book, BookItem};
-use crate::errors::*;
+use anyhow::Result;
 use log::warn;
 
 /// A preprocessor for converting file name `README.md` to `index.md` since
diff --git a/src/preprocess/links.rs b/src/preprocess/links.rs
@@ -1,8 +1,8 @@
-use crate::errors::*;
 use crate::utils::{
     take_anchored_lines, take_lines, take_rustdoc_include_anchored_lines,
     take_rustdoc_include_lines,
 };
+use anyhow::{Context, Result};
 use regex::{CaptureMatches, Captures, Regex};
 use std::fs;
 use std::ops::{Bound, Range, RangeBounds, RangeFrom, RangeFull, RangeTo};
diff --git a/src/preprocess/mod.rs b/src/preprocess/mod.rs
@@ -10,7 +10,7 @@ mod links;
 
 use crate::book::Book;
 use crate::config::Config;
-use crate::errors::*;
+use anyhow::Result;
 
 use serde::{Deserialize, Serialize};
 use std::cell::RefCell;
diff --git a/src/renderer/html_handlebars/hbs_renderer.rs b/src/renderer/html_handlebars/hbs_renderer.rs
@@ -1,11 +1,11 @@
 use crate::book::{Book, BookItem};
 use crate::config::{BookConfig, Code, Config, HtmlConfig, Playground, RustEdition};
-use crate::errors::*;
 use crate::renderer::html_handlebars::StaticFiles;
 use crate::renderer::html_handlebars::helpers;
 use crate::renderer::{RenderContext, Renderer};
 use crate::theme::{self, Theme};
 use crate::utils;
+use crate::utils::fs::get_404_output_file;
 
 use std::borrow::Cow;
 use std::collections::BTreeMap;
@@ -14,7 +14,7 @@ use std::fs::{self, File};
 use std::path::{Path, PathBuf};
 use std::sync::LazyLock;
 
-use crate::utils::fs::get_404_output_file;
+use anyhow::{Context, Result, bail};
 use handlebars::Handlebars;
 use log::{debug, info, trace, warn};
 use regex::{Captures, Regex};
diff --git a/src/renderer/html_handlebars/search.rs b/src/renderer/html_handlebars/search.rs
@@ -3,17 +3,17 @@ use std::collections::{HashMap, HashSet};
 use std::path::{Path, PathBuf};
 use std::sync::LazyLock;
 
+use anyhow::{Context, Result, bail};
 use elasticlunr::{Index, IndexBuilder};
+use log::{debug, warn};
 use pulldown_cmark::*;
+use serde::Serialize;
 
 use crate::book::{Book, BookItem, Chapter};
 use crate::config::{Search, SearchChapterSettings};
-use crate::errors::*;
 use crate::renderer::html_handlebars::StaticFiles;
 use crate::theme::searcher;
 use crate::utils;
-use log::{debug, warn};
-use serde::Serialize;
 
 const MAX_WORD_LENGTH_TO_INDEX: usize = 80;
 
diff --git a/src/renderer/html_handlebars/static_files.rs b/src/renderer/html_handlebars/static_files.rs
@@ -1,9 +1,9 @@
 //! Support for writing static files.
 
+use anyhow::{Context, Result};
 use log::{debug, warn};
 
 use crate::config::HtmlConfig;
-use crate::errors::*;
 use crate::renderer::html_handlebars::helpers::resources::ResourceHelper;
 use crate::theme::{self, Theme, playground_editor};
 use crate::utils;
diff --git a/src/renderer/markdown_renderer.rs b/src/renderer/markdown_renderer.rs
@@ -1,7 +1,7 @@
 use crate::book::BookItem;
-use crate::errors::*;
 use crate::renderer::{RenderContext, Renderer};
 use crate::utils;
+use anyhow::{Context, Result};
 use log::trace;
 use std::fs;
 
diff --git a/src/renderer/mod.rs b/src/renderer/mod.rs
diff --git a/src/utils/fs.rs b/src/utils/fs.rs
diff --git a/src/utils/mod.rs b/src/utils/mod.rs
diff --git a/tests/testsuite/preprocessor.rs b/tests/testsuite/preprocessor.rs
diff --git a/tests/testsuite/renderer.rs b/tests/testsuite/renderer.rs
diff --git a/tests/testsuite/toc.rs b/tests/testsuite/toc.rs
