dada_mdbook_preprocessor/

main.rs

use anyhow::{bail, Result};
use clap::{Arg, ArgMatches, Command};
use mdbook_preprocessor::book::{Book, BookItem, Chapter};
use mdbook_preprocessor::{Preprocessor, PreprocessorContext};
use regex::Regex;
use serde::Deserialize;
use std::collections::HashMap;
use std::io;
use std::path::Path;
use std::process;

pub fn make_app() -> Command {
    Command::new("dada-mdbook-preprocessor")
        .about("An mdbook preprocessor for processing Dada spec directives")
        .subcommand(
            Command::new("supports")
                .arg(Arg::new("renderer").required(true))
                .about("Check whether a renderer is supported by this preprocessor"),
        )
}

fn main() {
    let matches = make_app().get_matches();

    let preprocessor = DadaPreprocessor::new();

    if let Some(sub_args) = matches.subcommand_matches("supports") {
        handle_supports(&preprocessor, sub_args);
    } else if let Err(e) = handle_preprocessing(&preprocessor) {
        eprintln!("{e}");
        process::exit(1);
    }
}

fn handle_supports(pre: &dyn Preprocessor, sub_args: &ArgMatches) -> ! {
    let renderer = sub_args
        .get_one::<String>("renderer")
        .expect("Required argument");
    let supported = pre.supports_renderer(renderer).unwrap();

    if supported {
        process::exit(0);
    } else {
        process::exit(1);
    }
}

fn handle_preprocessing(pre: &dyn Preprocessor) -> Result<()> {
    let (ctx, book) = mdbook_preprocessor::parse_input(io::stdin())?;

    let book_version = Version::parse(&ctx.mdbook_version)?;
    let version_req = VersionReq::parse(mdbook_preprocessor::MDBOOK_VERSION)?;

    if !version_req.matches(&book_version) {
        eprintln!(
            "Warning: The {} plugin was built against version {} of mdbook, \
             but we're being called from version {}",
            pre.name(),
            mdbook_preprocessor::MDBOOK_VERSION,
            ctx.mdbook_version
        );
    }

    let processed_book = pre.run(&ctx, book)?;
    serde_json::to_writer(io::stdout(), &processed_book)?;

    Ok(())
}

use semver::{Version, VersionReq};

#[derive(Debug, Deserialize)]
struct RfcFrontMatter {
    status: String,
    #[serde(rename = "tracking-issue")]
    tracking_issue: Option<String>,
    #[serde(rename = "implemented-version")]
    implemented_version: Option<String>,
}

#[derive(Debug)]
struct RfcInfo {
    number: String,
    title: String,
    path: String,
    status: String,
    status_display: String,
    full_summary_markdown: String,
}

struct DadaPreprocessor;

impl DadaPreprocessor {
    pub fn new() -> DadaPreprocessor {
        DadaPreprocessor
    }
}

impl Preprocessor for DadaPreprocessor {
    fn name(&self) -> &str {
        "dada-mdbook-preprocessor"
    }

    fn run(&self, ctx: &PreprocessorContext, book: Book) -> Result<Book> {
        let mut book = book;
        // 💡 Match MyST directive syntax: `:::{spec} paragraph.id [rfcN...]`
        let re = Regex::new(r"^:::\{spec\}").unwrap();

        // Pre-pass: build nonterminal → URL map from headings like `## \`Function\` definition`
        let nt_map = build_nonterminal_map(&book);

        // First pass: process spec directives
        book.for_each_mut(|item: &mut BookItem| {
            if let BookItem::Chapter(chapter) = item {
                // Check if this chapter has any spec directives
                let has_labels = chapter.content.lines().any(|line| re.is_match(line.trim()));

                // Process the content
                chapter.content = process_spec_directives(
                    &chapter.content,
                    chapter.source_path.as_deref(),
                    &nt_map,
                );

                // If this chapter has labels, inject CSS at the end
                if has_labels {
                    chapter.content.push('\n');
                    chapter.content.push_str(&get_inline_css());
                }
            }
        });

        // Second pass: populate RFC sections
        populate_rfc_sections(ctx, &mut book)?;

        // Third pass: inject CSS for any chapters with RFC tables
        book.for_each_mut(|item: &mut BookItem| {
            if let BookItem::Chapter(chapter) = item {
                // Check if this chapter has RFC tables (after RFC generation)
                let has_rfc_tables = chapter.content.contains("class=\"rfc-table\"");

                // Check if CSS is already injected
                let already_has_css = chapter
                    .content
                    .contains("/* Generated by dada-mdbook-preprocessor");

                // If this chapter has RFC tables and doesn't already have CSS, inject it
                if has_rfc_tables && !already_has_css {
                    chapter.content.push('\n');
                    chapter.content.push_str(&get_inline_css());
                }
            }
        });

        Ok(book)
    }

    fn supports_renderer(&self, renderer: &str) -> Result<bool> {
        Ok(renderer != "not-supported")
    }
}

/// Scans all chapters for headings matching `` ## `Nonterminal` definition ``
/// and builds a map from nonterminal name to relative URL for cross-chapter linking.
///
/// 💡 The heading convention is `` ## `Function` definition `` which mdbook generates
/// as an anchor like `#function-definition`. For cross-chapter links, we also need
/// the chapter's path (e.g., `syntax/items.html`).
fn build_nonterminal_map(book: &Book) -> HashMap<String, String> {
    let heading_re = Regex::new(r"^#{2,6}\s+`([A-Z][A-Za-z]*)`\s+definition").unwrap();
    let mut map = HashMap::new();

    fn scan_items(items: &[BookItem], heading_re: &Regex, map: &mut HashMap<String, String>) {
        for item in items {
            if let BookItem::Chapter(chapter) = item {
                let chapter_path = chapter
                    .path
                    .as_ref()
                    .map(|p| p.with_extension("html").to_string_lossy().to_string())
                    .unwrap_or_default();

                for line in chapter.content.lines() {
                    if let Some(caps) = heading_re.captures(line.trim()) {
                        let nt_name = caps[1].to_string();
                        let anchor = format!("{}-definition", nt_name.to_lowercase());
                        let url = if chapter_path.is_empty() {
                            format!("#{anchor}")
                        } else {
                            format!("{chapter_path}#{anchor}")
                        };
                        map.insert(nt_name, url);
                    }
                }

                scan_items(&chapter.sub_items, heading_re, map);
            }
        }
    }

    scan_items(&book.items, &heading_re, &mut map);
    map
}

/// Processes MyST `{spec}` directives into HTML with anchors and styling.
///
/// 💡 Spec paragraph IDs are resolved from context:
/// - File path prefix derived from `source_path` (e.g., `syntax/string-literals.md` → `syntax.string-literals`)
/// - Current heading stack (e.g., `## Delimiters` → `delimiters`)
/// - Local name from the directive (e.g., `:::{spec} quoted` → `quoted`)
///
/// The directive `:::{spec} quoted rfc0001 unimpl` under `## Delimiters` in
/// `syntax/string-literals.md` resolves to `syntax.string-literals.delimiters.quoted`.
///
/// Inline sub-paragraphs `` {spec}`name` `` within a directive block create
/// individually linkable sub-paragraph anchors.
fn process_spec_directives(
    content: &str,
    source_path: Option<&Path>,
    nt_map: &HashMap<String, String>,
) -> String {
    // 💡 Changed from matching the full ID to just detecting the directive start.
    // The tokens after `{spec}` are parsed by `dada_spec_common::parse_spec_tokens`
    // to distinguish local names from tags.
    let directive_start = Regex::new(r"^:::\{spec\}(.*)$").unwrap();
    let directive_end = Regex::new(r"^:::$").unwrap();

    let file_prefix = source_path
        .map(dada_spec_common::file_path_to_prefix)
        .unwrap_or_default();
    let mut heading_tracker = dada_spec_common::HeadingTracker::new();

    let mut result = Vec::new();
    let mut in_directive = false;
    let mut current_id = String::new();
    let mut current_rfc_tags: Vec<String> = Vec::new();
    let mut directive_content: Vec<String> = Vec::new();

    for line in content.lines() {
        let trimmed = line.trim();

        if !in_directive {
            // Track headings for auto-prefix resolution
            heading_tracker.process_line(trimmed);

            if let Some(captures) = directive_start.captures(trimmed) {
                // Start of a spec directive
                in_directive = true;

                let rest = captures.get(1).map(|m| m.as_str()).unwrap_or("");
                let (local_name, tags) = dada_spec_common::parse_spec_tokens(rest);

                current_id = dada_spec_common::resolve_spec_id(
                    &file_prefix,
                    &heading_tracker.current_segments(),
                    local_name.as_deref().unwrap_or(""),
                );
                current_rfc_tags = tags;

                directive_content.clear();
            } else {
                result.push(line.to_string());
            }
        } else if directive_end.is_match(trimmed) {
            // End of directive - generate HTML
            let rfc_badges = dada_spec_common::render_tag_badges(&current_rfc_tags);

            // Expand EBNF `...` placeholders from sub-paragraph names
            let expanded_content = dada_spec_common::expand_ebnf_in_directive(&directive_content);

            // Convert EBNF code fences to HTML with linked nonterminals
            let linked_content = render_ebnf_blocks(&expanded_content, nt_map, source_path);

            // Transform inline sub-paragraphs in the content
            let transformed_content =
                dada_spec_common::transform_inline_sub_paragraphs(&linked_content, &current_id);

            // Generate HTML wrapper
            result.push(format!(
                "<div class=\"spec-paragraph\" id=\"{current_id}\">"
            ));
            result.push(format!(
                "<div class=\"spec-label\"><a href=\"#{current_id}\" class=\"spec-label-link\">{current_id}</a>{rfc_badges}</div>"
            ));
            result.push("<div class=\"spec-content\">".to_string());
            result.push(String::new()); // Empty line for markdown processing
            for content_line in &transformed_content {
                result.push(content_line.clone());
            }
            result.push(String::new()); // Empty line for markdown processing
            result.push("</div>".to_string());
            result.push("</div>".to_string());

            in_directive = false;
            current_id.clear();
            current_rfc_tags.clear();
        } else {
            // Inside directive - collect content
            directive_content.push(line.to_string());
        }
    }

    result.join("\n")
}

/// Converts markdown ` ```ebnf ``` ` code fences into HTML `<pre>` blocks with linked nonterminals.
///
/// Within EBNF blocks:
/// - PascalCase words that exist in `nt_map` become `<a>` links to their definition
/// - Backtick-quoted terminals become `<code class="ebnf-t">` spans
///
/// 💡 Links are made relative to the current chapter. If the nonterminal is defined
/// in a different chapter, we compute a relative path; if same chapter, just `#anchor`.
fn render_ebnf_blocks(
    content_lines: &[String],
    nt_map: &HashMap<String, String>,
    current_source: Option<&Path>,
) -> Vec<String> {
    let current_html_path = current_source
        .map(|p| p.with_extension("html").to_string_lossy().to_string())
        .unwrap_or_default();

    let mut in_ebnf = false;
    let mut ebnf_lines: Vec<String> = Vec::new();
    let mut result = Vec::new();

    for line in content_lines {
        let trimmed = line.trim();

        if trimmed == "```ebnf" {
            in_ebnf = true;
            ebnf_lines.clear();
        } else if trimmed == "```" && in_ebnf {
            in_ebnf = false;
            // Render the collected EBNF as HTML
            result.push("<pre class=\"ebnf-block\"><code>".to_string());
            for ebnf_line in &ebnf_lines {
                let rendered = render_ebnf_line(ebnf_line, nt_map, &current_html_path);
                result.push(rendered);
            }
            result.push("</code></pre>".to_string());
        } else if in_ebnf {
            ebnf_lines.push(line.clone());
        } else {
            result.push(line.clone());
        }
    }

    result
}

/// Renders a single EBNF line, replacing nonterminal references with links
/// and backtick-quoted terminals with styled `<code>` spans.
fn render_ebnf_line(
    line: &str,
    nt_map: &HashMap<String, String>,
    current_html_path: &str,
) -> String {
    let mut result = String::new();
    let mut chars = line.chars().peekable();

    while let Some(&ch) = chars.peek() {
        if ch == '`' {
            // Terminal in backticks
            chars.next(); // consume opening backtick
            let mut terminal = String::new();
            while let Some(&c) = chars.peek() {
                if c == '`' {
                    chars.next(); // consume closing backtick
                    break;
                }
                terminal.push(c);
                chars.next();
            }
            result.push_str(&format!(
                "<span class=\"ebnf-t\">{}</span>",
                html_escape(&terminal)
            ));
        } else if ch.is_uppercase() {
            // Potential nonterminal — collect PascalCase word
            let mut word = String::new();
            while let Some(&c) = chars.peek() {
                if c.is_alphanumeric() {
                    word.push(c);
                    chars.next();
                } else {
                    break;
                }
            }
            if let Some(url) = nt_map.get(&word) {
                // 💡 Make the link relative to the current chapter.
                let href = make_relative_link(url, current_html_path);
                result.push_str(&format!("<a href=\"{href}\" class=\"ebnf-nt\">{word}</a>"));
            } else {
                result.push_str(&word);
            }
        } else {
            // Regular character — HTML-escape it
            match ch {
                '<' => result.push_str("&lt;"),
                '>' => result.push_str("&gt;"),
                '&' => result.push_str("&amp;"),
                _ => result.push(ch),
            }
            chars.next();
        }
    }

    result
}

/// Escapes HTML special characters in terminal content.
fn html_escape(s: &str) -> String {
    s.replace('&', "&amp;")
        .replace('<', "&lt;")
        .replace('>', "&gt;")
}

/// Computes a relative link from `current_path` to `target_url`.
///
/// If the target is in the same file, returns just the `#anchor` part.
/// Otherwise returns a relative path like `../syntax/items.html#anchor`.
fn make_relative_link(target_url: &str, current_path: &str) -> String {
    if let Some(hash_pos) = target_url.find('#') {
        let target_file = &target_url[..hash_pos];
        let anchor = &target_url[hash_pos..];

        if target_file == current_path || target_file.is_empty() {
            // Same file — just the anchor
            anchor.to_string()
        } else {
            // 💡 Compute relative path: go up from current dir, then down to target.
            let current_dir = std::path::Path::new(current_path)
                .parent()
                .map(|p| p.to_str().unwrap_or(""))
                .unwrap_or("");
            if current_dir.is_empty() {
                target_url.to_string()
            } else {
                let depth = current_dir.matches('/').count() + 1;
                let up = "../".repeat(depth);
                format!("{up}{target_file}{anchor}")
            }
        }
    } else {
        target_url.to_string()
    }
}

/// 💡 Returns inline CSS with blank lines stripped. Blank lines inside `<style>` tags
/// cause mdbook's markdown processor to insert `<p>` tags, which breaks the CSS.
fn get_inline_css() -> String {
    let css = r#"<style>
/* Generated by dada-mdbook-preprocessor - Styling for specification paragraphs */
.spec-paragraph {
    margin: 1rem 0;
    padding: 0.75rem 1rem;
    border-left: 3px solid #d0d7de;
    background-color: #f8f9fa;
    border-radius: 0 4px 4px 0;
}

.spec-label {
    margin-bottom: 0.5rem;
    display: flex;
    align-items: center;
    gap: 0.5rem;
    flex-wrap: wrap;
}

.spec-label-link {
    font-size: 0.75rem;
    color: #666;
    text-decoration: none;
    font-family: 'SFMono-Regular', 'Monaco', 'Inconsolata', 'Fira Code', 'Source Code Pro', monospace;
    background-color: #fff;
    padding: 0.125rem 0.375rem;
    border-radius: 0.25rem;
    border: 1px solid #d0d7de;
}

.spec-label-link:hover {
    color: #0366d6;
    background-color: #f1f8ff;
    border-color: #c8e1ff;
    text-decoration: none;
}

.spec-content {
    margin: 0;
}

.spec-content > p:first-child {
    margin-top: 0;
}

.spec-content > p:last-child {
    margin-bottom: 0;
}

.spec-rfc-badge {
    font-size: 0.65rem;
    color: #fff;
    background-color: #0969da;
    padding: 0.1rem 0.3rem;
    border-radius: 0.25rem;
    font-family: 'SFMono-Regular', 'Monaco', 'Inconsolata', 'Fira Code', 'Source Code Pro', monospace;
}

.spec-rfc-badge.spec-rfc-deleted {
    background-color: #cf222e;
}

.spec-rfc-badge.spec-rfc-unimpl {
    background-color: #bf8700;
}

.spec-sub-label {
    font-size: 0.65rem;
    color: #999;
    text-decoration: none;
    font-family: 'SFMono-Regular', 'Monaco', 'Inconsolata', 'Fira Code', 'Source Code Pro', monospace;
}

.spec-sub-label:hover {
    color: #0366d6;
    text-decoration: none;
}

/* EBNF grammar blocks — inherits mdbook's default pre/code styling */
.ebnf-block > code {
    background: none;
    border: none;
    padding: 0;
}

.ebnf-nt {
    color: #0969da;
    text-decoration: none;
}

.ebnf-nt:hover {
    text-decoration: underline;
}

.ebnf-t {
    color: #0a3069;
    background-color: rgba(175, 184, 193, 0.2);
    padding: 0.1rem 0.3rem;
    border-radius: 3px;
}

/* Dark theme support */
.navy .spec-paragraph {
    border-color: #30363d;
    background-color: #161b22;
}

.navy .spec-label-link {
    color: #c5c5c5;
    background-color: #21262d;
    border-color: #30363d;
}

.navy .spec-label-link:hover {
    color: #79b8ff;
    background-color: #1c2128;
    border-color: #30363d;
}

.navy .spec-rfc-badge {
    background-color: #58a6ff;
    color: #0d1117;
}

.navy .spec-rfc-badge.spec-rfc-deleted {
    background-color: #f85149;
}

.navy .spec-rfc-badge.spec-rfc-unimpl {
    background-color: #d29922;
    color: #0d1117;
}

.navy .spec-sub-label {
    color: #7d8590;
}

.navy .spec-sub-label:hover {
    color: #79b8ff;
}

.navy .ebnf-nt {
    color: #58a6ff;
}

.navy .ebnf-t {
    color: #79c0ff;
    background-color: rgba(110, 118, 129, 0.2);
}

/* RFC Table Styling - GitHub-inspired */
.rfc-table {
    width: 100%;
    border-collapse: collapse;
    margin-bottom: 1.5rem;
    border: 1px solid #d0d7de;
    border-radius: 6px;
    overflow: hidden;
}

.rfc-header-row {
    background-color: #f6f8fa;
    border-bottom: 1px solid #d0d7de;
}

.rfc-header-row:hover {
    background-color: #f1f8ff;
}

.rfc-number {
    width: 60px;
    padding: 12px 16px;
    text-align: center;
    font-weight: 600;
    font-size: 14px;
    color: #656d76;
    background-color: inherit;
}

.rfc-details {
    display: flex;
    align-items: center;
    justify-content: center;
}

.rfc-details summary {
    cursor: pointer;
    list-style: none;
    display: flex;
    align-items: center;
    justify-content: center;
    position: relative;
}

.rfc-details summary::-webkit-details-marker {
    display: none;
}

.rfc-details summary::before {
    content: "▶";
    font-size: 10px;
    margin-right: 6px;
    transition: transform 0.2s ease;
}

.rfc-details[open] summary::before {
    transform: rotate(90deg);
}

.rfc-title {
    padding: 12px 16px;
    font-weight: 600;
    font-size: 14px;
}

.rfc-title a {
    color: #0969da;
    text-decoration: none;
}

.rfc-title a:hover {
    text-decoration: underline;
}

.rfc-summary-row {
    display: none;
}

.rfc-details[open] ~ .rfc-header-row ~ .rfc-summary-row,
.rfc-table:has(.rfc-details[open]) .rfc-summary-row {
    display: table-row;
}

.rfc-summary-content {
    padding: 16px;
    font-size: 13px;
    color: #656d76;
    font-weight: normal;
    border-top: 1px solid #d0d7de;
    background-color: #f8f9fa;
}

.rfc-status {
    width: 120px;
    padding: 12px 16px;
    text-align: center;
    vertical-align: middle;
}

/* Dark theme support for RFC tables */
.navy .rfc-table {
    border-color: #30363d;
}

.navy .rfc-header-row {
    background-color: #21262d;
    border-color: #30363d;
}

.navy .rfc-header-row:hover {
    background-color: #1c2128;
}

.navy .rfc-number {
    color: #7d8590;
}

.navy .rfc-title a {
    color: #58a6ff;
}

.navy .rfc-summary-content {
    border-color: #30363d;
    color: #7d8590;
    background-color: #161b22;
}
</style>"#;
    css.lines()
        .filter(|line| !line.trim().is_empty())
        .collect::<Vec<_>>()
        .join("\n")
}

fn populate_rfc_sections(ctx: &PreprocessorContext, book: &mut Book) -> Result<()> {
    // Find the position of the "All RFCs" chapter
    let mut rfc_chapter_index = None;

    for (index, item) in book.items.iter().enumerate() {
        if let BookItem::Chapter(chapter) = item {
            // Check if this is the All RFCs chapter
            if chapter.name.trim() == "All RFCs" {
                rfc_chapter_index = Some(index);
                break;
            }
        }
    }

    // If we found the All RFCs chapter, populate it
    if let Some(index) = rfc_chapter_index {
        // Get a mutable reference to the chapter
        if let Some(BookItem::Chapter(chapter)) = book.items.get_mut(index) {
            populate_all_rfcs_section(ctx, chapter)?;
        }
    }

    Ok(())
}

fn populate_all_rfcs_section(ctx: &PreprocessorContext, chapter: &mut Chapter) -> Result<()> {
    let src_dir = ctx.config.book.src.clone();

    // Find all RFC directories
    let mut rfc_dirs = Vec::new();
    if let Ok(entries) = std::fs::read_dir(&src_dir) {
        for entry in entries {
            let entry = entry?;
            let path = entry.path();
            if path.is_dir() {
                if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
                    // Match directories like 0001-feature-name
                    if name.len() > 4
                        && name[..4].chars().all(|c| c.is_ascii_digit())
                        && name.chars().nth(4) == Some('-')
                    {
                        rfc_dirs.push((name.to_string(), path));
                    }
                }
            }
        }
    }

    // Sort by RFC number
    rfc_dirs.sort_by(|a, b| a.0.cmp(&b.0));

    // Process each RFC directory to extract info
    let mut rfcs_by_status: HashMap<String, Vec<RfcInfo>> = HashMap::new();

    for (dir_name, dir_path) in rfc_dirs {
        if let Ok(rfc_info) = extract_rfc_info(&dir_path, &dir_name) {
            rfcs_by_status
                .entry(rfc_info.status.clone())
                .or_default()
                .push(rfc_info);
        }
    }

    // Generate HTML content for the all.md page
    let html_content = generate_all_rfcs_html(&rfcs_by_status);

    // Replace the chapter content
    chapter.content = format!("# All RFCs\n\n{html_content}");

    // Process each RFC directory for sub-chapters (keep existing functionality)
    let src_dir = ctx.config.book.src.clone();
    let mut rfc_dirs = Vec::new();
    if let Ok(entries) = std::fs::read_dir(&src_dir) {
        for entry in entries {
            let entry = entry?;
            let path = entry.path();
            if path.is_dir() {
                if let Some(name) = path.file_name().and_then(|n| n.to_str()) {
                    if name.len() > 4
                        && name[..4].chars().all(|c| c.is_ascii_digit())
                        && name.chars().nth(4) == Some('-')
                    {
                        rfc_dirs.push((name.to_string(), path));
                    }
                }
            }
        }
    }
    rfc_dirs.sort_by(|a, b| a.0.cmp(&b.0));

    for ((dir_name, dir_path), index) in rfc_dirs.iter().zip(0..) {
        if let Ok(rfc_chapter) = create_rfc_chapter(&src_dir, dir_name, dir_path, chapter, index) {
            chapter.sub_items.push(BookItem::Chapter(rfc_chapter));
        }
    }

    Ok(())
}

fn create_rfc_chapter(
    src_dir: &Path,
    dir_name: &str,
    dir_path: &Path,
    all_rfcs_chapter: &Chapter,
    rfc_index: u32,
) -> Result<Chapter> {
    // Read README.md to get the title
    let readme_path = dir_path.join("README.md");
    let readme_content = std::fs::read_to_string(&readme_path)?;

    // Extract title from first # line
    let title = readme_content
        .lines()
        .find(|line| line.starts_with("# "))
        .map(|line| line[2..].trim())
        .unwrap_or(dir_name)
        .to_string();

    // Create relative path for mdbook
    let relative_path = readme_path.strip_prefix(src_dir)?.to_path_buf();

    // Create proper parent names for nested structure
    let mut rfc_parent_names = all_rfcs_chapter.parent_names.clone();
    rfc_parent_names.push(all_rfcs_chapter.name.clone());

    // Get the section number of the parent and convert it to the section number of the new child
    let Some(mut section_number) = all_rfcs_chapter.number.clone() else {
        bail!("All RFCs chapter has no number")
    };
    section_number.push(rfc_index);

    let mut rfc_chapter = Chapter::new(
        &title,
        readme_content,
        relative_path,
        rfc_parent_names.clone(),
    );
    rfc_chapter.number = Some(section_number.clone());

    // Find all other .md files in the directory
    if let Ok(entries) = std::fs::read_dir(dir_path) {
        let mut sub_files = Vec::new();

        for entry in entries {
            let entry = entry?;
            let path = entry.path();

            if path.is_file() && path.extension().and_then(|s| s.to_str()) == Some("md") {
                let file_name = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
                if file_name != "README.md" {
                    sub_files.push(path);
                }
            }
        }

        // Sort sub-files for consistent ordering
        sub_files.sort();

        // Create sub-chapters for each .md file
        let mut sub_parent_names = rfc_parent_names.clone();
        sub_parent_names.push(title.clone());

        for (sub_path, sub_index) in sub_files.iter().zip(0..) {
            if let Ok(sub_content) = std::fs::read_to_string(sub_path) {
                // Extract title from first # line
                let sub_title = sub_content
                    .lines()
                    .find(|line| line.starts_with("# "))
                    .map(|line| line[2..].trim())
                    .unwrap_or_else(|| {
                        sub_path
                            .file_stem()
                            .and_then(|s| s.to_str())
                            .unwrap_or("Untitled")
                    })
                    .to_string();

                let sub_relative_path = sub_path.strip_prefix(src_dir)?.to_path_buf();

                let mut sub_chapter = Chapter::new(
                    &sub_title,
                    sub_content,
                    sub_relative_path,
                    sub_parent_names.clone(),
                );

                // assign the section number for this subchapter
                section_number.push(sub_index);
                sub_chapter.number = Some(section_number.clone());
                section_number.pop().unwrap();

                rfc_chapter.sub_items.push(BookItem::Chapter(sub_chapter));
            }
        }
    }

    Ok(rfc_chapter)
}

fn extract_rfc_info(dir_path: &Path, dir_name: &str) -> Result<RfcInfo> {
    // Read README.md to get the title and content
    let readme_path = dir_path.join("README.md");
    let readme_content = std::fs::read_to_string(&readme_path)?;

    // Parse front matter and content
    let (front_matter, content) = parse_front_matter(&readme_content)?;

    // Extract RFC number from directory name (e.g., "0001-string-literals" -> "0001")
    let number = dir_name[..4].to_string();

    // Extract title from first # line
    let title = content
        .lines()
        .find(|line| line.starts_with("# "))
        .map(|line| line[2..].trim())
        .unwrap_or(dir_name)
        .to_string();

    // Extract summary section
    let summary_section = extract_section(&content, "## Summary");

    // Generate status display
    let status_display = format_status(
        &front_matter.status,
        &front_matter.tracking_issue,
        &front_matter.implemented_version,
    );

    Ok(RfcInfo {
        number,
        title,
        path: dir_name.to_string(),
        status: front_matter.status,
        status_display,
        full_summary_markdown: summary_section,
    })
}

fn parse_front_matter(content: &str) -> Result<(RfcFrontMatter, String)> {
    let lines: Vec<&str> = content.lines().collect();

    // Check if content starts with front matter
    if lines.is_empty() || !lines[0].trim().starts_with("---") {
        // No front matter, use defaults
        let default_front_matter = RfcFrontMatter {
            status: "draft".to_string(),
            tracking_issue: None,
            implemented_version: None,
        };
        return Ok((default_front_matter, content.to_string()));
    }

    // Find the end of front matter
    let mut end_index = None;
    for (i, line) in lines.iter().enumerate().skip(1) {
        if line.trim() == "---" {
            end_index = Some(i);
            break;
        }
    }

    let end_index = end_index.ok_or_else(|| anyhow::anyhow!("Unclosed front matter"))?;

    // Extract and parse front matter
    let front_matter_text = lines[1..end_index].join("\n");
    let front_matter: RfcFrontMatter =
        serde_yaml::from_str(&front_matter_text).unwrap_or_else(|_| RfcFrontMatter {
            status: "draft".to_string(),
            tracking_issue: None,
            implemented_version: None,
        });

    // Extract content after front matter
    let content_lines = if end_index + 1 < lines.len() {
        &lines[end_index + 1..]
    } else {
        &[]
    };
    let content = content_lines.join("\n");

    Ok((front_matter, content))
}

fn extract_section(content: &str, heading: &str) -> String {
    let lines: Vec<&str> = content.lines().collect();
    let mut in_section = false;
    let mut section_lines = Vec::new();

    for line in lines {
        if line.starts_with("## ") {
            if line.trim() == heading {
                in_section = true;
                continue; // Skip the heading itself
            } else if in_section {
                break; // Hit next section, stop
            }
        }

        if in_section {
            section_lines.push(line);
        }
    }

    section_lines.join("\n").trim().to_string()
}

fn format_status(
    status: &str,
    tracking_issue: &Option<String>,
    implemented_version: &Option<String>,
) -> String {
    let (color, label) = match status {
        "active" => ("blue", "Active"),
        "accepted" => ("green", "Accepted"),
        "implemented" => ("brightgreen", "Implemented"),
        "draft" => ("lightgrey", "Draft"),
        "rejected" => ("red", "Rejected"),
        "withdrawn" => ("red", "Withdrawn"),
        _ => ("lightgrey", "Unknown"),
    };

    let mut badge_text = label.to_string();

    // Add version info if implemented
    if let Some(version) = implemented_version {
        badge_text = format!("{badge_text} v{version}");
    }

    // Add tracking issue if present
    if let Some(issue) = tracking_issue {
        if issue.chars().all(|c| c.is_ascii_digit()) {
            badge_text = format!("{badge_text} %23{issue}"); // %23 is URL-encoded #
        } else if let Some(issue_num) = issue.strip_prefix('#') {
            if issue_num.chars().all(|c| c.is_ascii_digit()) {
                badge_text = format!("{badge_text} %23{issue_num}");
            }
        }
    }

    // URL encode spaces and other characters
    let encoded_text = badge_text.replace(" ", "%20");

    let badge_url = format!("https://img.shields.io/badge/Status-{encoded_text}-{color}");

    // Generate HTML img tag instead of markdown since we're in an HTML table
    if let Some(issue) = tracking_issue {
        if issue.chars().all(|c| c.is_ascii_digit())
            || (issue.starts_with('#') && issue[1..].chars().all(|c| c.is_ascii_digit()))
        {
            let issue_num = issue.strip_prefix('#').unwrap_or(issue);
            let github_url = format!("https://github.com/dada-lang/dada/issues/{issue_num}");
            format!("<a href=\"{github_url}\"><img src=\"{badge_url}\" alt=\"RFC Status\" /></a>")
        } else {
            format!("<img src=\"{badge_url}\" alt=\"RFC Status\" />")
        }
    } else {
        format!("<img src=\"{badge_url}\" alt=\"RFC Status\" />")
    }
}

fn generate_all_rfcs_html(rfcs_by_status: &HashMap<String, Vec<RfcInfo>>) -> String {
    let mut content = String::new();

    content.push_str("This page provides an overview of all RFCs (Request for Comments) in the Dada language development process.\n\n");

    // Define status order for display
    let status_headers = [
        (
            "active",
            "Active RFCs",
            "RFCs currently under discussion and development.",
        ),
        (
            "accepted",
            "Accepted RFCs",
            "RFCs that have been accepted but not yet implemented.",
        ),
        (
            "implemented",
            "Implemented RFCs",
            "RFCs that have been fully implemented and are part of the language.",
        ),
        (
            "draft",
            "Draft RFCs",
            "RFCs that are still being written or refined.",
        ),
        (
            "rejected",
            "Rejected/Withdrawn RFCs",
            "RFCs that were not accepted or were withdrawn.",
        ),
    ];

    for (status, header, description) in status_headers {
        if let Some(rfcs) = rfcs_by_status.get(status) {
            if !rfcs.is_empty() {
                content.push_str(&format!("## {header}\n\n"));
                content.push_str(&format!("{description}\n\n"));
                content.push_str(&generate_rfc_table_html(rfcs));
                content.push('\n');
            } else {
                // Show empty sections for non-draft/rejected statuses
                if status != "rejected" {
                    content.push_str(&format!("## {header}\n\n"));
                    content.push_str(&format!("{description}\n\n"));
                    content.push_str("*(None yet)*\n");
                    content.push('\n');
                }
            }
        } else {
            // Show empty sections for non-draft/rejected statuses
            if status != "rejected" {
                content.push_str(&format!("## {header}\n\n"));
                content.push_str(&format!("{description}\n\n"));
                content.push_str("*(None yet)*\n");
                content.push('\n');
            }
        }
    }

    content
}

fn generate_rfc_table_html(rfcs: &[RfcInfo]) -> String {
    let mut html = String::new();

    for rfc in rfcs {
        let rfc_number = rfc.number.parse::<u32>().unwrap_or(0);
        // ⚠️ IMPORTANT: The blank lines around {} in rfc-summary-content are REQUIRED!
        // They allow mdbook's markdown processor to parse markdown inside HTML blocks.
        // Without these newlines, content like `code` and **bold** won't be rendered.
        html.push_str(&format!(
            r#"<table class="rfc-table">
<tr class="rfc-header-row">
<td class="rfc-number">
<details class="rfc-details">
<summary>{}</summary>
</details>
</td>
<td class="rfc-title"><a href="./{}/README.md">{}</a></td>
<td class="rfc-status">{}</td>
</tr>
<tr class="rfc-summary-row">
<td colspan="3" class="rfc-summary-content">

{}

</td>
</tr>
</table>

"#,
            rfc_number,
            rfc.path,
            rfc.title,
            rfc.status_display,
            rfc.full_summary_markdown.trim()
        ));
    }

    html
}