feat: ignore files listed in .mdbookignore during build

crates/mdbook-core/Cargo.toml

@@ -9,6 +9,8 @@ rust-version.workspace = true
 
 [dependencies]
 anyhow.workspace = true
+ignore.workspace = true
+pathdiff.workspace = true
 regex.workspace = true
 serde.workspace = true
 serde_json.workspace = true

crates/mdbook-core/src/utils/fs.rs

@@ -1,6 +1,7 @@
 //! Filesystem utilities and helpers.
 
 use anyhow::{Context, Result};
+use ignore::gitignore::Gitignore;
 use std::fs;
 use std::path::{Component, Path, PathBuf};
 use tracing::debug;
@@ -96,12 +97,30 @@ pub fn copy_files_except_ext(
     recursive: bool,
     avoid_dir: Option<&PathBuf>,
     ext_blacklist: &[&str],
+) -> Result<()> {
+    let mut builder = ignore::gitignore::GitignoreBuilder::new(from);
+    for ext in ext_blacklist {
+        builder.add_line(None, &format!("*.{ext}"))?;
+    }
+    let ignore = builder.build()?;
+
+    copy_files_except_ignored(from, to, recursive, avoid_dir, Some(&ignore))
+}
+
+/// Copies all files of a directory to another one except the files that are
+/// ignored by the passed [`Gitignore`]
+pub fn copy_files_except_ignored(
+    from: &Path,
+    to: &Path,
+    recursive: bool,
+    avoid_dir: Option<&PathBuf>,
+    ignore: Option<&Gitignore>,
 ) -> Result<()> {
     debug!(
-        "Copying all files from {} to {} (blacklist: {:?}), avoiding {:?}",
+        "Copying all files from {} to {} (ignoring: {:?}), avoiding {:?}",
         from.display(),
         to.display(),
-        ext_blacklist,
+        ignore,
         avoid_dir
     );
 
@@ -131,16 +150,25 @@ pub fn copy_files_except_ext(
                 }
             }
 
+            if let Some(ignore) = ignore {
+                let relative_path =
+                    pathdiff::diff_paths(&entry, from).unwrap_or_else(|| entry.to_path_buf());
+                if ignore.matched(&relative_path, true).is_ignore() {
+                    continue;
+                }
+            }
+
             // check if output dir already exists
             if !target_file_path.exists() {
                 fs::create_dir(&target_file_path)?;
             }
 
-            copy_files_except_ext(&entry, &target_file_path, true, avoid_dir, ext_blacklist)?;
+            copy_files_except_ignored(&entry, &target_file_path, true, avoid_dir, ignore)?;
         } else if metadata.is_file() {
-            // Check if it is in the blacklist
-            if let Some(ext) = entry.extension() {
-                if ext_blacklist.contains(&ext.to_str().unwrap()) {
+            if let Some(ignore) = ignore {
+                let relative_path =
+                    pathdiff::diff_paths(&entry, from).unwrap_or_else(|| entry.to_path_buf());
+                if ignore.matched(&relative_path, false).is_ignore() {
                     continue;
                 }
             }
@@ -210,6 +238,7 @@ fn copy<P: AsRef<Path>, Q: AsRef<Path>>(from: P, to: Q) -> Result<()> {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use ignore::gitignore::GitignoreBuilder;
     use std::io::Result;
     use std::path::Path;
 
@@ -270,4 +299,56 @@ mod tests {
             panic!("output/symlink.png should exist")
         }
     }
+
+    #[test]
+    fn copy_files_except_ignored_test() {
+        let tmp = match tempfile::TempDir::new() {
+            Ok(t) => t,
+            Err(e) => panic!("Could not create a temp dir: {e}"),
+        };
+
+        // Create files and directories
+        write(tmp.path().join("file.txt"), "").unwrap();
+        write(tmp.path().join("file.json"), "").unwrap();
+        write(tmp.path().join("ignored_dir/nested.txt"), "").unwrap();
+        write(tmp.path().join("included_dir/file.json"), "").unwrap();
+        write(tmp.path().join("included_dir/file.txt"), "").unwrap();
+
+        // Create a gitignore that ignores *.txt and ignored_dir/
+        let mut builder = GitignoreBuilder::new(tmp.path());
+        builder.add_line(None, "*.txt").unwrap();
+        builder.add_line(None, "ignored_dir/").unwrap();
+        let ignore = builder.build().unwrap();
+
+        // Create output dir
+        create_dir_all(tmp.path().join("output")).unwrap();
+
+        copy_files_except_ignored(
+            tmp.path(),
+            &tmp.path().join("output"),
+            true,
+            None,
+            Some(&ignore),
+        )
+        .unwrap();
+
+        // Check that .txt files are ignored
+        if tmp.path().join("output/file.txt").exists() {
+            panic!("output/file.txt should not exist")
+        }
+        if tmp.path().join("output/included_dir/file.txt").exists() {
+            panic!("output/included_dir/file.txt should not exist")
+        }
+        // Check that ignored_dir is not copied
+        if tmp.path().join("output/ignored_dir").exists() {
+            panic!("output/ignored_dir should not exist")
+        }
+        // Check that non-ignored files are copied
+        if !tmp.path().join("output/file.json").exists() {
+            panic!("output/file.json should exist")
+        }
+        if !tmp.path().join("output/included_dir/file.json").exists() {
+            panic!("output/included_dir/file.json should exist")
+        }
+    }
 }

crates/mdbook-html/Cargo.toml

@@ -15,6 +15,7 @@ font-awesome-as-a-crate.workspace = true
 handlebars.workspace = true
 hex.workspace = true
 html5ever.workspace = true
+ignore.workspace = true
 indexmap.workspace = true
 mdbook-core.workspace = true
 mdbook-markdown.workspace = true

crates/mdbook-html/src/html_handlebars/hbs_renderer.rs

@@ -6,6 +6,7 @@ use crate::theme::Theme;
 use crate::utils::ToUrlPath;
 use anyhow::{Context, Result, bail};
 use handlebars::Handlebars;
+use ignore::gitignore::GitignoreBuilder;
 use mdbook_core::book::{Book, BookItem, Chapter};
 use mdbook_core::config::{BookConfig, Config, HtmlConfig};
 use mdbook_core::utils::fs;
@@ -444,7 +445,31 @@ impl Renderer for HtmlHandlebars {
             .context("Unable to emit redirects")?;
 
         // Copy all remaining files, avoid a recursive copy from/to the book build dir
-        fs::copy_files_except_ext(&src_dir, destination, true, Some(&build_dir), &["md"])?;
+        let mut builder = GitignoreBuilder::new(&src_dir);
+
+        // Add default ignores
+        builder.add_line(None, "/.mdbookignore")?;
+        builder.add_line(None, "/.gitignore")?;
+        builder.add_line(None, "/.git/")?;
+        builder.add_line(None, "/book.toml")?;
+        builder.add_line(None, "/theme/")?;
+        builder.add_line(None, "*.md")?;
+
+        let mdbook_ignore = src_dir.join(".mdbookignore");
+        if mdbook_ignore.exists() {
+            if let Some(err) = builder.add(mdbook_ignore) {
+                warn!("Unable to load '.mdbookignore' file: {}", err);
+            }
+        }
+        let ignore = builder.build()?;
+
+        fs::copy_files_except_ignored(
+            &src_dir,
+            destination,
+            true,
+            Some(&build_dir),
+            Some(&ignore),
+        )?;
 
         info!("HTML book written to `{}`", destination.display());
 

guide/src/format/configuration/renderers.md

@@ -322,6 +322,18 @@ This will generate an HTML page which will automatically redirect to the given l
 
 When fragment redirects are specified, the page must use JavaScript to redirect to the correct location. This is useful if you rename or move a section header. Fragment redirects work with existing pages and deleted pages.
 
+### `.mdbookignore`
+
+You can use a `.mdbookignore` file to exclude files from the build process.  
+The file is placed in the `src` directory of your book and has the format known  
+from [`.gitignore`](https://git-scm.com/docs/gitignore) files.
+
+For example:
+```
+*.rs
+/target/
+```
+
 ## Markdown renderer
 
 The Markdown renderer will run preprocessors and then output the resulting

tests/testsuite/build.rs

@@ -85,3 +85,18 @@ fn dest_dir_relative_path() {
     });
     assert!(current_dir.join("foo/index.html").exists());
 }
+
+// Test that .mdbookignore files are respected (single files, glob patterns, and directories).
+#[test]
+fn mdbookignore() {
+    let mut test = BookTest::from_dir("build/mdbookignore");
+    test.build();
+    // Single file listed by name should not be copied.
+    assert!(!test.dir.join("book/ignored_file").exists());
+    // Files matching *.txt glob pattern should not be copied.
+    assert!(!test.dir.join("book/ignored.txt").exists());
+    // Directories listed in .mdbookignore should not be copied.
+    assert!(!test.dir.join("book/ignored_dir").exists());
+    // Non-ignored files should be copied.
+    assert!(test.dir.join("book/included.json").exists());
+}

tests/testsuite/build/mdbookignore/book.toml

@@ -0,0 +1,2 @@
+[book]
+title = "mdbookignore test"

tests/testsuite/build/mdbookignore/src/.mdbookignore

@@ -0,0 +1,3 @@
+ignored_file
+*.txt
+ignored_dir/

tests/testsuite/build/mdbookignore/src/SUMMARY.md

@@ -0,0 +1,3 @@
+# Summary
+
+- [Chapter 1](./chapter_1.md)

tests/testsuite/build/mdbookignore/src/chapter_1.md

@@ -0,0 +1,3 @@
+# Chapter 1
+
+This is chapter 1.

tests/testsuite/build/mdbookignore/src/ignored.txt

@@ -0,0 +1 @@
+This txt file should not be copied.

tests/testsuite/build/mdbookignore/src/ignored_dir/file.json

@@ -0,0 +1 @@
+This file in ignored dir should not be copied.

tests/testsuite/build/mdbookignore/src/ignored_file

@@ -0,0 +1 @@
+This file should not be copied.

tests/testsuite/build/mdbookignore/src/included.json

@@ -0,0 +1 @@
+This file should be copied.

tests/testsuite/build/mdbookignore/src/theme/css/custom.css

@@ -0,0 +1 @@
+/* custom theme */

tests/testsuite/build/mdbookignore/src/theme/fonts/fonts.css

@@ -0,0 +1 @@
+@font-face { }