fifthtry_mdbook/preprocess/
index.rs

1use regex::Regex;
2use std::path::Path;
3
4use crate::errors::*;
5
6use super::{Preprocessor, PreprocessorContext};
7use crate::book::{Book, BookItem};
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    lazy_static! {
71        static ref RE: Regex = Regex::new(r"(?i)^readme$").unwrap();
72    }
73    RE.is_match(
74        path.as_ref()
75            .file_stem()
76            .and_then(std::ffi::OsStr::to_str)
77            .unwrap_or_default(),
78    )
79}
80
81#[cfg(test)]
82mod tests {
83    use super::*;
84
85    #[test]
86    fn file_stem_exactly_matches_readme_case_insensitively() {
87        let path = "path/to/Readme.md";
88        assert!(is_readme_file(path));
89
90        let path = "path/to/README.md";
91        assert!(is_readme_file(path));
92
93        let path = "path/to/rEaDmE.md";
94        assert!(is_readme_file(path));
95
96        let path = "path/to/README.markdown";
97        assert!(is_readme_file(path));
98
99        let path = "path/to/README";
100        assert!(is_readme_file(path));
101
102        let path = "path/to/README-README.md";
103        assert!(!is_readme_file(path));
104    }
105}
fifthtry_mdbook/preprocess/index.rs

fifthtry_mdbook/preprocess/
index.rs
