mdbook_content_collections/

lib.rs

use anyhow::Result;
use chrono::{DateTime, NaiveDate, TimeZone, Utc};
use pulldown_cmark::{Options, Parser, html};
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::json;
use std::{fs, path::Path, time::SystemTime};
use walkdir::WalkDir;

// Minimum body length (in chars) before we prefer it over description
const MIN_BODY_PREVIEW_CHARS: usize = 80;

// Convert file modification time → UTC
fn systemtime_to_utc(st: SystemTime) -> DateTime<Utc> {
    DateTime::<Utc>::from(st)
}

// Parse front-matter date formats
fn deserialize_date<'de, D>(deserializer: D) -> Result<Option<DateTime<Utc>>, D::Error>
where
    D: Deserializer<'de>,
{
    let s: Option<String> = Option::deserialize(deserializer)?;

    if let Some(date_str) = s {
        if let Ok(dt) = DateTime::parse_from_rfc3339(&date_str) {
            return Ok(Some(dt.with_timezone(&Utc)));
        }

        if let Ok(nd) = NaiveDate::parse_from_str(&date_str, "%Y-%m-%d") {
            return Ok(Some(
                Utc.from_utc_datetime(&nd.and_hms_opt(0, 0, 0).unwrap()),
            ));
        }
    }
    Ok(None)
}

#[derive(Debug, Deserialize, Clone)]
pub struct FrontMatter {
    pub title: String,

    #[serde(deserialize_with = "deserialize_date")]
    pub date: Option<DateTime<Utc>>,

    pub author: Option<String>,
    pub description: Option<String>, // User-supplied summary (optional)

    // New: optional collection name
    pub collection: Option<String>,

    // New: simple tags array for indexing
    pub tags: Option<Vec<String>>,

    // New: draft flag
    pub draft: Option<bool>,
}

#[derive(Debug)]
pub struct Article {
    pub fm: FrontMatter,
    pub content: String,
    pub path: String,
}

/// Parses a markdown file to extract YAML front matter and content.
///
/// # Errors
///
/// This function returns an error if the file cannot be read.
///
/// # Panics
///
/// Panics if the provided `path` does not have a valid file name (e.g., it terminates in `..`),
/// as a title cannot be generated from the file stem.
pub fn parse_markdown_file(root: &Path, path: &Path) -> Result<Article> {
    let text = fs::read_to_string(path)?;

    let mut lines = text.lines();
    let mut yaml = String::new();
    let mut in_yaml = false;

    // Extract YAML front matter
    for line in lines.by_ref() {
        let trimmed = line.trim();
        if trimmed == "---" {
            if !in_yaml {
                in_yaml = true;
                continue;
            }
            break;
        }
        if in_yaml {
            yaml.push_str(line);
            yaml.push('\n');
        }
    }

    // Markdown content after front matter
    let content = lines.collect::<Vec<_>>().join("\n") + "\n";

    let fallback_date = path
        .metadata()
        .ok()
        .and_then(|m| m.modified().ok())
        .map(systemtime_to_utc);

    // Parse front matter
    let fm = if yaml.trim().is_empty() {
        FrontMatter {
            title: path.file_stem().unwrap().to_string_lossy().into_owned(),
            date: fallback_date,
            author: None,
            description: Some(content.clone()),
            collection: None,
            tags: None,
            draft: None,
        }
    } else {
        serde_yml::from_str(&yaml).unwrap_or_else(|_| FrontMatter {
            title: path.file_stem().unwrap().to_string_lossy().into_owned(),
            date: fallback_date,
            author: None,
            description: Some(content.clone()),
            collection: None,
            tags: None,
            draft: None,
        })
    };

    let rel_path = path.strip_prefix(root).unwrap_or(path);

    Ok(Article {
        fm,
        content,
        path: rel_path.to_string_lossy().into_owned(),
    })
}

/// Traverses the source directory to collect and parse all Markdown files.
///
/// It ignores `SUMMARY.md` and non-markdown files. Articles are returned
/// sorted by date in descending order (newest first).
///
/// # Errors
///
/// Returns an error if:
/// * The `src_dir` cannot be accessed or does not exist.
/// * An I/O error occurs while walking the directory tree (e.g., permission denied).
/// * A markdown file exists but cannot be read during the parsing phase.
pub fn collect_articles(src_dir: &Path) -> Result<Vec<Article>> {
    let mut articles = Vec::new();

    for entry in WalkDir::new(src_dir)
        .into_iter()
        .filter_map(std::result::Result::ok)
    {
        let path = entry.path();

        // 1. Filter out directories
        if !path.is_file() {
            continue;
        }

        // 2. Check extension safely
        let is_markdown = path
            .extension()
            .and_then(|e| e.to_str())
            .map(str::to_ascii_lowercase)
            .is_some_and(|s| s == "md" || s == "markdown");

        if !is_markdown {
            continue;
        }

        // 3. Check for SUMMARY.md safely
        // map_or(false, ...) returns false if file_name() is None
        let is_summary = path
            .file_name()
            .map(|name| name.to_string_lossy())
            .is_some_and(|name| name.eq_ignore_ascii_case("SUMMARY.md"));

        if is_summary {
            continue;
        }

        // 4. Parse the file
        if let Ok(article) = parse_markdown_file(src_dir, path) {
            articles.push(article);
        }
    }

    // Sort newest → oldest
    articles.sort_by_key(|a| a.fm.date);
    articles.reverse();

    Ok(articles)
}

fn markdown_to_html(md: &str) -> String {
    let mut html = String::new();
    let parser = Parser::new_ext(md, Options::all());
    html::push_html(&mut html, parser);
    html
}

/// Strip obvious leading boilerplate (TOCs, details, long definition blocks)
/// so previews tend to start at the main intro text instead of metadata.
fn strip_leading_boilerplate(md: &str) -> &str {
    let mut seen_heading = false;
    let mut byte_idx = 0;
    let mut acc_bytes = 0;

    for (i, line) in md.lines().enumerate() {
        let line_len_with_nl = line.len() + 1; // assume '\n' separated

        // Skip initial blank lines entirely
        if i == 0 && line.trim().is_empty() {
            acc_bytes += line_len_with_nl;
            continue;
        }

        if line.trim_start().starts_with('#') {
            seen_heading = true;
        }

        if seen_heading && line.trim().is_empty() {
            // First blank line after heading: start preview after this
            acc_bytes += line_len_with_nl;
            byte_idx = acc_bytes;
            break;
        }

        acc_bytes += line_len_with_nl;
    }

    if byte_idx == 0 {
        md
    } else {
        &md[byte_idx.min(md.len())..]
    }
}

/// Take at most `max_chars` worth of UTF‑8 text from `s`.
fn utf8_prefix(s: &str, max_chars: usize) -> &str {
    if max_chars == 0 {
        return "";
    }

    let mut last_byte = 0;

    for (ch_idx, (byte_idx, _)) in s.char_indices().enumerate() {
        if ch_idx == max_chars {
            last_byte = byte_idx;
            break;
        }
        last_byte = byte_idx + 1;
    }

    if last_byte == 0 || last_byte >= s.len() {
        s
    } else {
        &s[..last_byte]
    }
}

/// Take up to `max_paragraphs` <p> blocks from HTML, and cap at `max_chars` (UTF-8 safe).
fn html_first_paragraphs(html: &str, max_paragraphs: usize, max_chars: usize) -> String {
    let mut out = String::new();
    let mut start = 0;
    let mut count = 0;

    while count < max_paragraphs {
        // Find next <p ...>
        let Some(rel) = html[start..].find("<p") else {
            break;
        };
        let p_start = start + rel;

        // Find the end of this paragraph
        let Some(rel_close) = html[p_start..].find("</p>") else {
            break;
        };
        let close = p_start + rel_close + "</p>".len();

        let para = &html[p_start..close];
        out.push_str(para);
        count += 1;
        start = close;
    }

    // If no <p> found, fall back to original HTML
    if out.is_empty() {
        out = html.to_string();
    }

    // UTF‑8 safe trim by character count
    if out.chars().count() > max_chars {
        out.chars().take(max_chars).collect()
    } else {
        out
    }
}

#[derive(Debug, Serialize)]
pub struct ContentEntry {
    pub path: String, // relative path in src
    pub title: String,
    pub date: Option<String>,
    pub author: Option<String>,
    pub description: Option<String>,
    pub collection: Option<String>,
    pub tags: Vec<String>,
    pub draft: bool,
    pub preview_html: String,
}

/// Builds a JSON index of all articles and writes it to the specified output path.
///
/// This function processes markdown content into HTML previews and bundles
/// metadata (tags, dates, authors) into a structured format used by the
/// Kanagawa landing page.
///
/// # Errors
///
/// Returns an error if:
/// * [`collect_articles`] fails due to I/O issues in the source directory.
/// * The parent directory of `output_path` cannot be created.
/// * The final JSON structure fails to serialize.
/// * The index file cannot be written to `output_path` (e.g., disk is full or permission denied).
pub fn build_content_index(src_dir: &Path, output_path: &Path) -> Result<()> {
    const PREVIEW_MD_SLICE_CHARS: usize = 4000;
    let articles = collect_articles(src_dir)?;

    let entries: Vec<ContentEntry> = articles
        .into_iter()
        .map(|article| {
            let content_trimmed = article.content.trim();
            let body_len = content_trimmed.chars().count();

            let mut source_md =
                if body_len >= MIN_BODY_PREVIEW_CHARS || article.fm.description.is_none() {
                    content_trimmed
                } else {
                    article.fm.description.as_deref().unwrap_or(content_trimmed)
                };

            source_md = strip_leading_boilerplate(source_md);

            let source_md_slice = utf8_prefix(source_md, PREVIEW_MD_SLICE_CHARS);

            let raw_html = markdown_to_html(source_md_slice);
            let preview_html = html_first_paragraphs(&raw_html, 3, 800);

            ContentEntry {
                path: article.path,
                title: article.fm.title,
                date: article.fm.date.map(|d| d.to_rfc3339()),
                author: article.fm.author,
                description: article.fm.description,
                collection: article.fm.collection,
                tags: article.fm.tags.unwrap_or_default(),
                draft: article.fm.draft.unwrap_or(false),
                preview_html,
            }
        })
        .collect();

    // Very simple index shape for now
    let index = json!({
        "entries": entries,
    });

    if let Some(parent) = output_path.parent() {
        fs::create_dir_all(parent)?;
    }

    fs::write(output_path, serde_json::to_vec_pretty(&index)?)?;

    Ok(())
}