mdbook/preprocess/
index.rs

1use regex::Regex;
2use std::{path::Path, sync::LazyLock};
3
4use super::{Preprocessor, PreprocessorContext};
5use crate::book::{Book, BookItem};
6use crate::errors::*;
7use log::warn;
8
9/// A preprocessor for converting file name `README.md` to `index.md` since
10/// `README.md` is the de facto index file in markdown-based documentation.
11#[derive(Default)]
12pub struct IndexPreprocessor;
13
14impl IndexPreprocessor {
15    pub(crate) const NAME: &'static str = "index";
16
17    /// Create a new `IndexPreprocessor`.
18    pub fn new() -> Self {
19        IndexPreprocessor
20    }
21}
22
23impl Preprocessor for IndexPreprocessor {
24    fn name(&self) -> &str {
25        Self::NAME
26    }
27
28    fn run(&self, ctx: &PreprocessorContext, mut book: Book) -> Result<Book> {
29        let source_dir = ctx.root.join(&ctx.config.book.src);
30        book.for_each_mut(|section: &mut BookItem| {
31            if let BookItem::Chapter(ref mut ch) = *section {
32                if let Some(ref mut path) = ch.path {
33                    if is_readme_file(&path) {
34                        let mut index_md = source_dir.join(path.with_file_name("index.md"));
35                        if index_md.exists() {
36                            warn_readme_name_conflict(&path, &&mut index_md);
37                        }
38
39                        path.set_file_name("index.md");
40                    }
41                }
42            }
43        });
44
45        Ok(book)
46    }
47}
48
49fn warn_readme_name_conflict<P: AsRef<Path>>(readme_path: P, index_path: P) {
50    let file_name = readme_path.as_ref().file_name().unwrap_or_default();
51    let parent_dir = index_path
52        .as_ref()
53        .parent()
54        .unwrap_or_else(|| index_path.as_ref());
55    warn!(
56        "It seems that there are both {:?} and index.md under \"{}\".",
57        file_name,
58        parent_dir.display()
59    );
60    warn!(
61        "mdbook converts {:?} into index.html by default. It may cause",
62        file_name
63    );
64    warn!("unexpected behavior if putting both files under the same directory.");
65    warn!("To solve the warning, try to rearrange the book structure or disable");
66    warn!("\"index\" preprocessor to stop the conversion.");
67}
68
69fn is_readme_file<P: AsRef<Path>>(path: P) -> bool {
70    static RE: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"(?i)^readme$").unwrap());
71
72    RE.is_match(
73        path.as_ref()
74            .file_stem()
75            .and_then(std::ffi::OsStr::to_str)
76            .unwrap_or_default(),
77    )
78}
79
80#[cfg(test)]
81mod tests {
82    use super::*;
83
84    #[test]
85    fn file_stem_exactly_matches_readme_case_insensitively() {
86        let path = "path/to/Readme.md";
87        assert!(is_readme_file(path));
88
89        let path = "path/to/README.md";
90        assert!(is_readme_file(path));
91
92        let path = "path/to/rEaDmE.md";
93        assert!(is_readme_file(path));
94
95        let path = "path/to/README.markdown";
96        assert!(is_readme_file(path));
97
98        let path = "path/to/README";
99        assert!(is_readme_file(path));
100
101        let path = "path/to/README-README.md";
102        assert!(!is_readme_file(path));
103    }
104}
mdbook/preprocess/index.rs

mdbook/preprocess/
index.rs
