From 29b02718e3328f1be9dab1eb72f778ea17bd88d3 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 10:16:56 +0000 Subject: [PATCH 01/34] feat(html-generator): :sparkles: v0.0.2 --- Cargo.toml | 6 +++--- README.md | 4 ++-- TEMPLATE.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index abfe033..8a4bf07 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ [package] name = "html-generator" -version = "0.0.1" +version = "0.0.2" edition = "2021" rust-version = "1.56.0" license = "MIT OR Apache-2.0" @@ -40,13 +40,13 @@ path = "src/lib.rs" [dependencies] # Dependencies required for building and running the project. -comrak = "0.29" +comrak = "0.31.0" frontmatter-gen = "0.0.5" lazy_static = "1.5" mdx-gen = "0.0.1" minify-html = "0.15" once_cell = "1.20" -regex = "1.11" +regex = "1.11.1" scraper = "0.21" serde = { version = "1.0", features = ["derive"] } serde_json = "1.0" diff --git a/README.md b/README.md index 8c5269d..bdb82c0 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ Add this to your `Cargo.toml`: ```toml [dependencies] -html-generator = "0.0.1" +html-generator = "0.0.2" ``` ## Usage @@ -117,5 +117,5 @@ Special thanks to all contributors who have helped build the `html-generator` li [crates-badge]: https://img.shields.io/crates/v/html-generator.svg?style=for-the-badge&color=fc8d62&logo=rust [docs-badge]: https://img.shields.io/badge/docs.rs-metadata--gen-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs [github-badge]: https://img.shields.io/badge/github-sebastienrousseau/metadata--gen-8da0cb?style=for-the-badge&labelColor=555555&logo=github -[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.1-orange.svg?style=for-the-badge +[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.2-orange.svg?style=for-the-badge [made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust diff --git a/TEMPLATE.md b/TEMPLATE.md index eca4ab5..d33dcbc 100644 --- a/TEMPLATE.md +++ b/TEMPLATE.md @@ -50,7 +50,7 @@ The `html-generator` is a robust Rust library designed for transforming Markdown [crates-badge]: https://img.shields.io/crates/v/html-generator.svg?style=for-the-badge&color=fc8d62&logo=rust [docs-badge]: https://img.shields.io/badge/docs.rs-metadata--gen-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs [github-badge]: https://img.shields.io/badge/github-sebastienrousseau/metadata--gen-8da0cb?style=for-the-badge&labelColor=555555&logo=github -[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.1-orange.svg?style=for-the-badge +[libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.2-orange.svg?style=for-the-badge [made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust ## Changelog 📚 From 748b6cf226e278dabe27f851a06d513f02e8f0bc Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 12:17:29 +0000 Subject: [PATCH 02/34] fix(html-generator): :arrow_up: upgrade dependencies and cleaning up --- Cargo.toml | 199 ++++++++++++++++++++++++++++++++++-- src/lib.rs | 2 +- tools/check_dependencies.sh | 38 +++++++ 3 files changed, 232 insertions(+), 7 deletions(-) create mode 100644 tools/check_dependencies.sh diff --git a/Cargo.toml b/Cargo.toml index 8a4bf07..e6e56da 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -28,8 +28,35 @@ categories = [ "development-tools" ] +# Keywords for easier discoverability on Crates.io. keywords = ["html", "web_development", "seo", "html-generator"] +# Excluding unnecessary files from the package +exclude = [ + "/.git/*", # Exclude version control files + "/.github/*", # Exclude GitHub workflows + "/.gitignore", # Ignore Git ignore file + "/.vscode/*" # Ignore VSCode settings +] + +# Including necessary files in the package +include = [ + "/CONTRIBUTING.md", + "/LICENSE-APACHE", + "/LICENSE-MIT", + "/benches/**", + "/build.rs", + "/Cargo.toml", + "/examples/**", + "/README.md", + "/src/**", +] + +# ----------------------------------------------------------------------------- +# Library Information +# ----------------------------------------------------------------------------- + +# The library file that contains the main logic for the binary. [lib] name = "html_generator" path = "src/lib.rs" @@ -41,15 +68,12 @@ path = "src/lib.rs" [dependencies] # Dependencies required for building and running the project. comrak = "0.31.0" -frontmatter-gen = "0.0.5" lazy_static = "1.5" mdx-gen = "0.0.1" minify-html = "0.15" once_cell = "1.20" regex = "1.11.1" scraper = "0.21" -serde = { version = "1.0", features = ["derive"] } -serde_json = "1.0" tempfile = "3.13" thiserror = "2.0" tokio = { version = "1.40", features = ["full"] } @@ -89,9 +113,172 @@ default = [] async = [] # ----------------------------------------------------------------------------- -# Documentation Configuration +# Examples # ----------------------------------------------------------------------------- +[[example]] +name = "accessibility" +path = "examples/accessibility_example.rs" + +[[example]] +name = "error" +path = "examples/error_example.rs" + +[[example]] +name = "generator" +path = "examples/generator_example.rs" + +[[example]] +name = "lib" +path = "examples/lib_example.rs" + +[[example]] +name = "performance" +path = "examples/performance_example.rs" + +[[example]] +name = "seo" +path = "examples/seo_example.rs" + +[[example]] +name = "utils" +path = "examples/utils_example.rs" + +# ----------------------------------------------------------------------------- +# Criterion Benchmark +# ----------------------------------------------------------------------------- +[[bench]] # Benchmarking configuration. +name = "html_benchmark" # Name of the benchmark. +harness = false # Disable the default benchmark harness. + +# ----------------------------------------------------------------------------- +# Documentation Configuration +# ----------------------------------------------------------------------------- [package.metadata.docs.rs] -all-features = true -rustdoc-args = ["--cfg", "docsrs"] +# Settings for building and hosting documentation on docs.rs. +all-features = true # Build documentation with all features enabled +rustdoc-args = ["--cfg", "docsrs"] # Arguments passed to `rustdoc` when building the documentation +targets = ["x86_64-unknown-linux-gnu"] # Default target platform for the docs + +# ----------------------------------------------------------------------------- +# Linting Configuration +# ----------------------------------------------------------------------------- +[lints.rust] +# Linting rules for the project. + +## Warnings +missing_copy_implementations = "warn" # Warn if types can implement `Copy` but don’t +missing_docs = "warn" # Warn if public items lack documentation +unstable_features = "warn" # Warn on the usage of unstable features +unused_extern_crates = "warn" # Warn about unused external crates +unused_results = "warn" # Warn if a result type is unused (e.g., errors ignored) + +## Allowances +bare_trait_objects = "allow" # Allow bare trait objects (e.g., `Box`) +elided_lifetimes_in_paths = "allow" # Allow lifetimes to be elided in paths +non_camel_case_types = "allow" # Allow non-camel-case types +non_upper_case_globals = "allow" # Allow non-uppercase global variables +trivial_bounds = "allow" # Allow trivial bounds in trait definitions +unsafe_code = "allow" # Allow the usage of unsafe code blocks + +## Forbidden +missing_debug_implementations = "forbid" # Forbid missing `Debug` implementations +non_ascii_idents = "forbid" # Forbid non-ASCII identifiers +unreachable_pub = "forbid" # Forbid unreachable `pub` items + +## Denials +dead_code = "deny" # Deny unused, dead code in the project +deprecated_in_future = "deny" # Deny code that will be deprecated in the future +ellipsis_inclusive_range_patterns = "deny" # Deny usage of inclusive ranges in match patterns (`...`) +explicit_outlives_requirements = "deny" # Deny unnecessary lifetime outlives requirements +future_incompatible = { level = "deny", priority = -1 } # Handle future compatibility issues +keyword_idents = { level = "deny", priority = -1 } # Deny usage of keywords as identifiers +macro_use_extern_crate = "deny" # Deny macro use of `extern crate` +meta_variable_misuse = "deny" # Deny misuse of meta variables in macros +missing_fragment_specifier = "deny" # Deny missing fragment specifiers in macros +noop_method_call = "deny" # Deny method calls that have no effect +rust_2018_idioms = { level = "deny", priority = -1 } # Enforce Rust 2018 idioms +rust_2021_compatibility = { level = "deny", priority = -1 } # Enforce Rust 2021 compatibility +single_use_lifetimes = "deny" # Deny lifetimes that are used only once +trivial_casts = "deny" # Deny trivial casts (e.g., `as` when unnecessary) +trivial_numeric_casts = "deny" # Deny trivial numeric casts (e.g., `i32` to `i64`) +unused = { level = "deny", priority = -1 } # Deny unused code, variables, etc. +unused_features = "deny" # Deny unused features +unused_import_braces = "deny" # Deny unnecessary braces around imports +unused_labels = "deny" # Deny unused labels in loops +unused_lifetimes = "deny" # Deny unused lifetimes +unused_macro_rules = "deny" # Deny unused macros +unused_qualifications = "deny" # Deny unnecessary type qualifications +variant_size_differences = "deny" # Deny enum variants with significant size differences + +# ----------------------------------------------------------------------------- +# Clippy Configuration +# ----------------------------------------------------------------------------- +[package.metadata.clippy] +# Clippy lint configuration for enhanced code analysis. +warn-lints = [ + "clippy::all", # Enable all common Clippy lints + "clippy::pedantic", # Enable pedantic lints for stricter checking + "clippy::cargo", # Enable lints specific to cargo + "clippy::nursery", # Enable experimental lints from Clippy’s nursery + "clippy::complexity", # Warn on code complexity and suggest improvements + "clippy::correctness", # Ensure code correctness, flagging potential issues + "clippy::perf", # Lints that catch performance issues + "clippy::style", # Suggest stylistic improvements + "clippy::suspicious", # Detect suspicious code patterns + "clippy::module_name_repetitions", # Avoid repeating module names in the crate name +] + +# Customize Clippy to allow certain less critical lints. +allow-lints = [ + "clippy::module_inception", # Allow modules with the same name as their parents + "clippy::too_many_arguments", # Allow functions with more than 7 arguments if justified + "clippy::missing_docs_in_private_items", # Skip requiring documentation for private items +] + +# Enforce specific warnings and errors more strictly. +deny-lints = [ + "clippy::unwrap_used", # Deny the use of unwrap to ensure error handling + "clippy::expect_used", # Deny the use of expect to avoid improper error handling +] + +# ----------------------------------------------------------------------------- +# Profiles +# ----------------------------------------------------------------------------- +[profile.dev] +# Development profile configuration for fast builds and debugging. +codegen-units = 256 # Increase codegen units for faster compilation +debug = true # Enable debugging symbols +debug-assertions = true # Enable debug assertions +incremental = true # Enable incremental compilation +lto = false # Disable link-time optimization for development +opt-level = 0 # No optimizations in development +overflow-checks = true # Enable overflow checks for arithmetic operations +panic = 'unwind' # Enable unwinding for panics (useful in development) +rpath = false # Disable rpath generation +strip = false # Do not strip symbols in development builds + +[profile.release] +# Release profile configuration for optimized builds. +codegen-units = 1 # Reduce codegen units for better performance +debug = false # Disable debug symbols in release builds +debug-assertions = false # Disable debug assertions +incremental = false # Disable incremental compilation for optimal binary size +lto = true # Enable link-time optimization for smaller and faster binaries +opt-level = "z" # Optimize for binary size +overflow-checks = false # Disable overflow checks for performance +panic = "abort" # Use abort on panic for minimal overhead +rpath = false # Disable rpath generation +strip = "symbols" # Strip symbols for smaller binary size + +[profile.test] +# Test profile configuration for debugging and development. +codegen-units = 256 # Increase codegen units for faster test builds +debug = true # Enable debugging symbols for test builds +debug-assertions = true # Enable debug assertions for tests +incremental = true # Enable incremental compilation for tests +lto = false # Disable link-time optimization during testing +opt-level = 0 # No optimizations in test builds +overflow-checks = true # Enable overflow checks for tests +rpath = false # Disable rpath generation +strip = false # Do not strip symbols in test builds diff --git a/src/lib.rs b/src/lib.rs index 7ff1c97..626df76 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -36,7 +36,7 @@ pub use utils::{extract_front_matter, format_header_with_id_class}; use thiserror::Error; /// Configuration options for HTML generation -#[derive(Debug, Clone)] +#[derive(Debug, Copy, Clone)] pub struct HtmlConfig { /// Enable syntax highlighting for code blocks pub enable_syntax_highlighting: bool, diff --git a/tools/check_dependencies.sh b/tools/check_dependencies.sh new file mode 100644 index 0000000..d1d9f9a --- /dev/null +++ b/tools/check_dependencies.sh @@ -0,0 +1,38 @@ +#!/bin/bash + +# Set the path to Cargo.toml relative to the script's location +cargo_toml="$(dirname "$0")/../Cargo.toml" + +# Set the directories to search in relative to the script's location +search_dirs=( + "$(dirname "$0")/../src/" + "$(dirname "$0")/../benches/" + "$(dirname "$0")/../examples/" + "$(dirname "$0")/../tests/" +) + +# Extract dependency names specifically from the `[dependencies]` section +dependencies=$(awk '/\[dependencies\]/ {flag=1; next} /^\[/{flag=0} flag {print}' "${cargo_toml}" | grep -oE '^[a-zA-Z0-9_-]+' || true) + +# Iterate over each dependency +while read -r dep; do + # Skip empty lines + [[ -z "${dep}" ]] && continue + + # Prepare a pattern to match Rust module imports (e.g., http-handle becomes http_handle) + dep_pattern=$(echo "${dep}" | tr '-' '_') + + # Check if the dependency is used in any of the specified directories + found=false + for dir in "${search_dirs[@]}"; do + if grep -qir "${dep_pattern}" "${dir}"; then + found=true + break + fi + done + + # If the dependency is not found in any directory, mark it as unused + if [[ "${found}" = false ]]; then + printf "🗑️ The \033[1m%s\033[0m crate is not required!\n" "${dep}" + fi +done <<< "${dependencies}" From 71f895d5767989de555dc0e977aedf2ab058c9df Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 15:22:36 +0000 Subject: [PATCH 03/34] refactor(html-generator): :art: implement comprehensive config builder and getters --- examples/error_example.rs | 25 +- examples/lib_example.rs | 23 +- src/error.rs | 554 ++++++++++++++++++++++++++++++++---- src/generator.rs | 8 +- src/lib.rs | 577 ++++++++++++++++++++++++++++++++++++-- src/performance.rs | 15 +- 6 files changed, 1096 insertions(+), 106 deletions(-) diff --git a/examples/error_example.rs b/examples/error_example.rs index 5823ad5..324f346 100644 --- a/examples/error_example.rs +++ b/examples/error_example.rs @@ -1,7 +1,9 @@ // src/examples/error_example.rs #![allow(missing_docs)] -use html_generator::error::HtmlError; +use html_generator::error::{ + AccessibilityErrorKind, HtmlError, SeoErrorKind, +}; /// Entry point for the html-generator error handling examples. /// @@ -97,7 +99,7 @@ fn io_error_example() -> Result<(), HtmlError> { std::io::ErrorKind::NotFound, "File not found", ); - let error = HtmlError::IoError(io_error); + let error = HtmlError::Io(io_error); println!(" ✅ Created IO Error: {}", error); Ok(()) @@ -148,8 +150,9 @@ fn markdown_conversion_error_example() -> Result<(), HtmlError> { println!("\n🦀 Markdown Conversion Error Example"); println!("---------------------------------------------"); - let error = HtmlError::MarkdownConversionError( + let error = HtmlError::markdown_conversion( "Failed to convert markdown".to_string(), + None, ); println!(" ✅ Created Markdown Conversion Error: {}", error); @@ -161,9 +164,11 @@ fn seo_optimization_error_example() -> Result<(), HtmlError> { println!("\n🦀 SEO Optimization Error Example"); println!("---------------------------------------------"); - let error = HtmlError::SeoOptimizationError( - "SEO issue occurred".to_string(), - ); + let error = HtmlError::Seo { + message: "SEO issue occurred".to_string(), + element: Some("meta".to_string()), + kind: SeoErrorKind::Other, + }; println!(" ✅ Created SEO Optimization Error: {}", error); Ok(()) @@ -174,9 +179,11 @@ fn accessibility_error_example() -> Result<(), HtmlError> { println!("\n🦀 Accessibility Error Example"); println!("---------------------------------------------"); - let error = HtmlError::AccessibilityError( - "Failed to add ARIA attributes".to_string(), - ); + let error = HtmlError::Accessibility { + message: "Failed to add ARIA attributes".to_string(), + kind: AccessibilityErrorKind::Other, + wcag_guideline: Some("1.1.1".to_string()), + }; println!(" ✅ Created Accessibility Error: {}", error); Ok(()) diff --git a/examples/lib_example.rs b/examples/lib_example.rs index 37f8d03..c794c52 100644 --- a/examples/lib_example.rs +++ b/examples/lib_example.rs @@ -3,9 +3,10 @@ #![allow(missing_docs)] use html_generator::{ - add_aria_attributes, async_generate_html, generate_html, - generate_meta_tags, generate_structured_data, HtmlConfig, - HtmlError, Result, + add_aria_attributes, async_generate_html, + error::{AccessibilityErrorKind, HtmlError}, + generate_html, generate_meta_tags, generate_structured_data, + HtmlConfig, Result, }; /// Entry point for the html-generator library usage examples. @@ -32,7 +33,7 @@ async fn main() -> Result<()> { /// Demonstrates basic HTML generation from Markdown content. fn basic_html_generation_example() -> Result<()> { - println!("🦀 Basic HTML Generation Example"); + println!("� Basic HTML Generation Example"); println!("---------------------------------------------"); let markdown = "# Welcome to html-generator!"; @@ -52,11 +53,15 @@ fn accessibility_example() -> Result<()> { let html = ""; // Map the error from `add_aria_attributes` to `HtmlError::AccessibilityError` - let updated_html = add_aria_attributes(html) - .map_err(|e| HtmlError::AccessibilityError(e.to_string()))?; + let updated_html = add_aria_attributes(html).map_err(|e| { + HtmlError::accessibility( + AccessibilityErrorKind::MissingAriaAttributes, + e.to_string(), + None, + ) + })?; println!("Updated HTML with ARIA attributes: \n{}", updated_html); - Ok(()) } @@ -81,9 +86,9 @@ fn seo_optimization_example() -> Result<()> { // Use a closure to convert the error type to HtmlError::SeoError, which expects a String let meta_tags = generate_meta_tags(html) - .map_err(|e| HtmlError::SeoError(e.to_string()))?; + .map_err(|e| HtmlError::MinificationError(e.to_string()))?; let structured_data = generate_structured_data(html) - .map_err(|e| HtmlError::SeoError(e.to_string()))?; + .map_err(|e| HtmlError::MinificationError(e.to_string()))?; println!("Generated Meta Tags: \n{}", meta_tags); println!("Generated Structured Data: \n{}", structured_data); diff --git a/src/error.rs b/src/error.rs index ba1545d..b906619 100644 --- a/src/error.rs +++ b/src/error.rs @@ -1,10 +1,9 @@ //! Error types for HTML generation and processing. //! //! This module defines custom error types used throughout the HTML generation library. -//! It provides a centralized location for all error definitions, making it easier to -//! manage and handle errors consistently across the codebase. +//! It provides a centralized location for all error definitions, making it easier to manage and handle errors consistently across the codebase. -use std::io::Error as IoError; +use std::io; use thiserror::Error; /// Enum to represent various errors that can occur during HTML generation, processing, or optimization. @@ -29,12 +28,6 @@ pub enum HtmlError { #[error("Failed to format header: {0}")] HeaderFormattingError(String), - /// Error for IO-related issues. - /// - /// This variant wraps standard IO errors and is used when an IO operation fails (e.g., reading or writing files). - #[error("IO error: {0}")] - IoError(#[from] IoError), - /// Error that occurs when parsing a selector fails. /// /// This variant is used when a CSS or HTML selector cannot be parsed. @@ -51,22 +44,48 @@ pub enum HtmlError { /// Error that occurs during the conversion of Markdown to HTML. /// /// This variant is used when the Markdown conversion process encounters an issue. The associated string provides more information. - #[error("Markdown conversion error: {0}")] - MarkdownConversionError(String), + #[error("Failed to convert Markdown to HTML: {message}")] + MarkdownConversion { + /// The error message + message: String, + /// The source error, if available + #[source] + source: Option, + }, - /// Error that occurs during SEO optimization. - /// - /// This variant is used when an SEO-related process fails, such as generating meta tags or structured data. - /// The associated string provides more context. - #[error("SEO optimization error: {0}")] - SeoOptimizationError(String), + /// Errors that occur during HTML minification. + #[error("HTML minification failed: {message}")] + Minification { + /// The error message + message: String, + /// The source error, if available + size: Option, + /// The source error, if available + #[source] + source: Option, + }, - /// Error that occurs when handling accessibility-related operations. - /// - /// This variant is used for errors that occur during accessibility checks or modifications (e.g., adding ARIA attributes). - /// The associated string provides more details. - #[error("Accessibility error: {0}")] - AccessibilityError(String), + /// SEO-related errors. + #[error("SEO optimization failed: {kind}: {message}")] + Seo { + /// The kind of SEO error + kind: SeoErrorKind, + /// The error message + message: String, + /// The problematic element, if available + element: Option, + }, + + /// Accessibility-related errors. + #[error("Accessibility check failed: {kind}: {message}")] + Accessibility { + /// The kind of accessibility error + kind: AccessibilityErrorKind, + /// The error message + message: String, + /// The relevant WCAG guideline, if available + wcag_guideline: Option, + }, /// Error indicating that a required HTML element is missing. /// @@ -80,6 +99,12 @@ pub enum HtmlError { #[error("Invalid structured data: {0}")] InvalidStructuredData(String), + /// Input/Output errors + /// + /// This variant is used when an IO operation fails (e.g., reading or writing files). + #[error("IO error: {0}")] + Io(#[from] io::Error), + /// Error indicating an invalid input. /// /// This variant is used when the input content is invalid or does not meet the expected criteria. @@ -116,6 +141,16 @@ pub enum HtmlError { #[error("Parsing error: {0}")] ParsingError(String), + /// Errors that occur during template rendering. + #[error("Template rendering failed: {message}")] + TemplateRendering { + /// The error message + message: String, + /// The source error, if available + #[source] + source: Box, + }, + /// Error indicating a validation failure. /// /// This variant is used when a validation step fails, such as schema validation or data integrity checks. @@ -127,10 +162,135 @@ pub enum HtmlError { /// This variant is used for errors that do not fit into other categories. #[error("Unexpected error: {0}")] UnexpectedError(String), +} - /// An SEO-related error. - #[error("SEO error: {0}")] - SeoError(String), +/// Types of SEO-related errors +#[derive(Debug, Copy, Clone, PartialEq, Eq)] +pub enum SeoErrorKind { + /// Missing required meta tags + MissingMetaTags, + /// Invalid structured data + InvalidStructuredData, + /// Missing title + MissingTitle, + /// Missing description + MissingDescription, + /// Other SEO-related errors + Other, +} + +/// Types of accessibility-related errors +#[derive(Debug, Copy, Clone, PartialEq, Eq)] +pub enum AccessibilityErrorKind { + /// Missing ARIA attributes + MissingAriaAttributes, + /// Invalid ARIA attribute values + InvalidAriaValue, + /// Missing alternative text + MissingAltText, + /// Incorrect heading structure + HeadingStructure, + /// Missing form labels + MissingFormLabels, + /// Other accessibility-related errors + Other, +} + +impl std::fmt::Display for AccessibilityErrorKind { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + AccessibilityErrorKind::MissingAriaAttributes => { + write!(f, "Missing ARIA attributes") + } + AccessibilityErrorKind::InvalidAriaValue => { + write!(f, "Invalid ARIA attribute values") + } + AccessibilityErrorKind::MissingAltText => { + write!(f, "Missing alternative text") + } + AccessibilityErrorKind::HeadingStructure => { + write!(f, "Incorrect heading structure") + } + AccessibilityErrorKind::MissingFormLabels => { + write!(f, "Missing form labels") + } + AccessibilityErrorKind::Other => { + write!(f, "Other accessibility-related errors") + } + } + } +} + +impl std::fmt::Display for SeoErrorKind { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + SeoErrorKind::MissingMetaTags => { + write!(f, "Missing required meta tags") + } + SeoErrorKind::InvalidStructuredData => { + write!(f, "Invalid structured data") + } + SeoErrorKind::MissingTitle => write!(f, "Missing title"), + SeoErrorKind::MissingDescription => { + write!(f, "Missing description") + } + SeoErrorKind::Other => { + write!(f, "Other SEO-related errors") + } + } + } +} + +impl HtmlError { + /// Creates a new InvalidInput error + pub fn invalid_input( + message: impl Into, + _input: Option, + ) -> Self { + Self::InvalidInput(message.into()) + } + + /// Creates a new InputTooLarge error + pub fn input_too_large(size: usize) -> Self { + Self::InputTooLarge(size) + } + + /// Creates a new Seo error + pub fn seo( + kind: SeoErrorKind, + message: impl Into, + element: Option, + ) -> Self { + Self::Seo { + kind, + message: message.into(), + element, + } + } + + /// Creates a new Accessibility error + pub fn accessibility( + kind: AccessibilityErrorKind, + message: impl Into, + wcag_guideline: Option, + ) -> Self { + Self::Accessibility { + kind, + message: message.into(), + wcag_guideline, + } + } + + /// Creates a new MarkdownConversion error + pub fn markdown_conversion( + message: impl Into, + source: Option, + ) -> Self { + Self::MarkdownConversion { + message: message.into(), + source, + } + } } /// Type alias for a result using the `HtmlError` error type. @@ -143,41 +303,323 @@ pub type Result = std::result::Result; mod tests { use super::*; - #[test] - fn test_html_error_display() { - let error = HtmlError::FrontMatterExtractionError( - "Invalid format".to_string(), - ); - assert_eq!( - error.to_string(), - "Failed to extract front matter: Invalid format" - ); + // Basic Error Creation Tests + mod basic_errors { + use super::*; + + #[test] + fn test_regex_compilation_error() { + let regex_error = + regex::Error::Syntax("invalid regex".to_string()); + let error: HtmlError = regex_error.into(); + assert!(matches!( + error, + HtmlError::RegexCompilationError(_) + )); + assert!(error + .to_string() + .contains("Failed to compile regex")); + } + + #[test] + fn test_front_matter_extraction_error() { + let error = HtmlError::FrontMatterExtractionError( + "Missing delimiter".to_string(), + ); + assert_eq!( + error.to_string(), + "Failed to extract front matter: Missing delimiter" + ); + } + + #[test] + fn test_header_formatting_error() { + let error = HtmlError::HeaderFormattingError( + "Invalid header level".to_string(), + ); + assert_eq!( + error.to_string(), + "Failed to format header: Invalid header level" + ); + } + + #[test] + fn test_selector_parse_error() { + let error = HtmlError::SelectorParseError( + "div>".to_string(), + "Unexpected end".to_string(), + ); + assert_eq!( + error.to_string(), + "Failed to parse selector 'div>': Unexpected end" + ); + } + + #[test] + fn test_minification_error() { + let error = HtmlError::MinificationError( + "Syntax error".to_string(), + ); + assert_eq!( + error.to_string(), + "Failed to minify HTML: Syntax error" + ); + } + } + + // Structured Error Tests + mod structured_errors { + use super::*; + + #[test] + fn test_markdown_conversion_with_source() { + let source = + io::Error::new(io::ErrorKind::Other, "source error"); + let error = HtmlError::markdown_conversion( + "Conversion failed", + Some(source), + ); + assert!(error + .to_string() + .contains("Failed to convert Markdown to HTML")); + } + + #[test] + fn test_markdown_conversion_without_source() { + let error = HtmlError::markdown_conversion( + "Conversion failed", + None, + ); + assert!(error.to_string().contains("Conversion failed")); + } + + #[test] + fn test_minification_with_size_and_source() { + let error = HtmlError::Minification { + message: "Too large".to_string(), + size: Some(1024), + source: Some(io::Error::new( + io::ErrorKind::Other, + "IO error", + )), + }; + assert!(error + .to_string() + .contains("HTML minification failed")); + } } - #[test] - fn test_html_error_from_io_error() { - let io_error = IoError::new( - std::io::ErrorKind::NotFound, - "File not found", - ); - let html_error: HtmlError = io_error.into(); + // SEO Error Tests + mod seo_errors { + use super::*; + + #[test] + fn test_seo_error_missing_meta_tags() { + let error = HtmlError::seo( + SeoErrorKind::MissingMetaTags, + "Required meta tags missing", + Some("head".to_string()), + ); + assert!(error + .to_string() + .contains("Missing required meta tags")); + } + + #[test] + fn test_seo_error_without_element() { + let error = HtmlError::seo( + SeoErrorKind::MissingTitle, + "Title not found", + None, + ); + assert!(error.to_string().contains("Missing title")); + } - // Use IoErrorKind to verify the correct error kind - if let HtmlError::IoError(e) = html_error { - assert_eq!(e.kind(), std::io::ErrorKind::NotFound); - } else { - panic!("Expected HtmlError::IoError"); + #[test] + fn test_all_seo_error_kinds() { + let kinds = [ + SeoErrorKind::MissingMetaTags, + SeoErrorKind::InvalidStructuredData, + SeoErrorKind::MissingTitle, + SeoErrorKind::MissingDescription, + SeoErrorKind::Other, + ]; + for kind in kinds { + assert!(!kind.to_string().is_empty()); + } } } - #[test] - fn test_html_error_from_utf8_error() { - let utf8_error = - String::from_utf8(vec![0, 159, 146, 150]).unwrap_err(); - let html_error: HtmlError = utf8_error.into(); - assert!(matches!( - html_error, - HtmlError::Utf8ConversionError(_) - )); + // Accessibility Error Tests + mod accessibility_errors { + use super::*; + + #[test] + fn test_accessibility_error_with_guideline() { + let error = HtmlError::accessibility( + AccessibilityErrorKind::MissingAltText, + "Images must have alt text", + Some("WCAG 1.1.1".to_string()), + ); + assert!(error + .to_string() + .contains("Missing alternative text")); + } + + #[test] + fn test_accessibility_error_without_guideline() { + let error = HtmlError::accessibility( + AccessibilityErrorKind::InvalidAriaValue, + "Invalid ARIA value", + None, + ); + assert!(error + .to_string() + .contains("Invalid ARIA attribute values")); + } + + #[test] + fn test_all_accessibility_error_kinds() { + let kinds = [ + AccessibilityErrorKind::MissingAriaAttributes, + AccessibilityErrorKind::InvalidAriaValue, + AccessibilityErrorKind::MissingAltText, + AccessibilityErrorKind::HeadingStructure, + AccessibilityErrorKind::MissingFormLabels, + AccessibilityErrorKind::Other, + ]; + for kind in kinds { + assert!(!kind.to_string().is_empty()); + } + } + } + + // Input/Output Error Tests + mod io_errors { + use super::*; + + #[test] + fn test_io_error_kinds() { + let error_kinds = [ + io::ErrorKind::NotFound, + io::ErrorKind::PermissionDenied, + io::ErrorKind::ConnectionRefused, + io::ErrorKind::ConnectionReset, + io::ErrorKind::ConnectionAborted, + io::ErrorKind::NotConnected, + io::ErrorKind::AddrInUse, + io::ErrorKind::AddrNotAvailable, + io::ErrorKind::BrokenPipe, + io::ErrorKind::AlreadyExists, + io::ErrorKind::WouldBlock, + io::ErrorKind::InvalidInput, + io::ErrorKind::InvalidData, + io::ErrorKind::TimedOut, + io::ErrorKind::WriteZero, + io::ErrorKind::Interrupted, + io::ErrorKind::Unsupported, + io::ErrorKind::UnexpectedEof, + io::ErrorKind::OutOfMemory, + io::ErrorKind::Other, + ]; + + for kind in error_kinds { + let io_error = io::Error::new(kind, "test error"); + let html_error: HtmlError = io_error.into(); + assert!(matches!(html_error, HtmlError::Io(_))); + } + } + } + + // Helper Method Tests + mod helper_methods { + use super::*; + + #[test] + fn test_invalid_input_with_content() { + let error = HtmlError::invalid_input( + "Bad input", + Some("problematic content".to_string()), + ); + assert!(error.to_string().contains("Invalid input")); + } + + #[test] + fn test_input_too_large() { + let error = HtmlError::input_too_large(1024); + assert!(error.to_string().contains("1024 bytes")); + } + + #[test] + fn test_template_rendering_error() { + let source_error = Box::new(io::Error::new( + io::ErrorKind::Other, + "render failed", + )); + let error = HtmlError::TemplateRendering { + message: "Template error".to_string(), + source: source_error, + }; + assert!(error + .to_string() + .contains("Template rendering failed")); + } + } + + // Miscellaneous Error Tests + mod misc_errors { + use super::*; + + #[test] + fn test_missing_html_element() { + let error = + HtmlError::MissingHtmlElement("title".to_string()); + assert!(error + .to_string() + .contains("Missing required HTML element")); + } + + #[test] + fn test_invalid_structured_data() { + let error = HtmlError::InvalidStructuredData( + "Invalid JSON-LD".to_string(), + ); + assert!(error + .to_string() + .contains("Invalid structured data")); + } + + #[test] + fn test_invalid_front_matter_format() { + let error = HtmlError::InvalidFrontMatterFormat( + "Missing closing delimiter".to_string(), + ); + assert!(error + .to_string() + .contains("Invalid front matter format")); + } + + #[test] + fn test_parsing_error() { + let error = + HtmlError::ParsingError("Unexpected token".to_string()); + assert!(error.to_string().contains("Parsing error")); + } + + #[test] + fn test_validation_error() { + let error = HtmlError::ValidationError( + "Schema validation failed".to_string(), + ); + assert!(error.to_string().contains("Validation error")); + } + + #[test] + fn test_unexpected_error() { + let error = HtmlError::UnexpectedError( + "Something went wrong".to_string(), + ); + assert!(error.to_string().contains("Unexpected error")); + } } } diff --git a/src/generator.rs b/src/generator.rs index 7c5a2b0..2c95402 100644 --- a/src/generator.rs +++ b/src/generator.rs @@ -4,8 +4,8 @@ //! using the `mdx-gen` library. It supports various Markdown extensions //! and custom configuration options. +use crate::error::HtmlError; use crate::extract_front_matter; -use crate::HtmlError; use crate::Result; use mdx_gen::{process_markdown, ComrakOptions, MarkdownOptions}; @@ -82,7 +82,11 @@ pub fn markdown_to_html_with_extensions( match process_markdown(&content_without_front_matter, &options) { Ok(html_output) => Ok(html_output), Err(err) => { - Err(HtmlError::MarkdownConversionError(err.to_string())) + // Using the helper method + Err(HtmlError::markdown_conversion( + err.to_string(), + None, // If err is not io::Error, use None + )) } } } diff --git a/src/lib.rs b/src/lib.rs index 626df76..d46b9e4 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -9,6 +9,32 @@ #![crate_name = "html_generator"] #![crate_type = "lib"] +//! HTML Generator: A modern HTML generation and optimization library +//! +//! This crate provides a comprehensive suite of tools for generating, optimizing, +//! and managing HTML content with a focus on accessibility, SEO, and performance. +//! +//! # Features +//! +//! - **HTML Generation**: Convert Markdown to HTML with customizable options +//! - **Accessibility**: Automated ARIA attributes and WCAG compliance checking +//! - **SEO Optimization**: Meta tag generation and structured data support +//! - **Performance**: HTML minification and async generation capabilities +//! +//! # Example +//! +//! ```rust +//! use html_generator::{generate_html, HtmlConfig}; +//! +//! let markdown = "# Hello World\n\nWelcome to HTML Generator."; +//! let config = HtmlConfig::default(); +//! +//! match generate_html(markdown, &config) { +//! Ok(html) => println!("Generated HTML: {}", html), +//! Err(e) => eprintln!("Error: {}", e), +//! } +//! ``` + /// The `accessibility` module contains functions for improving accessibility. pub mod accessibility; @@ -27,57 +53,558 @@ pub mod seo; /// The `utils` module contains utility functions. pub mod utils; +pub use crate::error::HtmlError; +/// Public API for the HTML Generator library pub use accessibility::{add_aria_attributes, validate_wcag}; pub use generator::generate_html; pub use performance::{async_generate_html, minify_html}; pub use seo::{generate_meta_tags, generate_structured_data}; pub use utils::{extract_front_matter, format_header_with_id_class}; -use thiserror::Error; +/// Common constants used throughout the library +pub mod constants { + /// Default maximum input size (5MB) + pub const DEFAULT_MAX_INPUT_SIZE: usize = 5 * 1024 * 1024; + + /// Default language + pub const DEFAULT_LANGUAGE: &str = "en-GB"; + + /// Default syntax theme + pub const DEFAULT_SYNTAX_THEME: &str = "github"; +} /// Configuration options for HTML generation -#[derive(Debug, Copy, Clone)] +#[derive(Debug, PartialEq, Eq, Clone)] pub struct HtmlConfig { - /// Enable syntax highlighting for code blocks + /// Enable syntax highlighting for code blocks. + /// + /// When enabled, code blocks in Markdown will be highlighted using the + /// specified theme. pub enable_syntax_highlighting: bool, - /// Minify the generated HTML output + + /// Theme to use for syntax highlighting. + /// + /// Only applicable when `enable_syntax_highlighting` is true. + pub syntax_theme: Option, + + /// Minify the generated HTML output. + /// + /// When enabled, removes unnecessary whitespace and comments to reduce + /// file size. pub minify_output: bool, - /// Automatically add ARIA attributes for accessibility + + /// Automatically add ARIA attributes for accessibility. pub add_aria_attributes: bool, - /// Generate structured data (JSON-LD) based on content + + /// Generate structured data (JSON-LD) based on content. pub generate_structured_data: bool, + + /// Maximum size (in bytes) for input content. + /// + /// Defaults to 5MB to prevent memory issues with large inputs. + pub max_input_size: usize, + + /// Language for generated content. + /// + /// Used for lang attributes and meta tags. + pub language: String, + + /// Enable table of contents generation. + pub generate_toc: bool, } impl Default for HtmlConfig { fn default() -> Self { - HtmlConfig { + Self { enable_syntax_highlighting: true, + syntax_theme: Some("github".to_string()), minify_output: false, add_aria_attributes: true, generate_structured_data: false, + max_input_size: 5 * 1024 * 1024, // 5MB + language: String::from("en-GB"), + generate_toc: false, } } } -/// Error type for HTML generation -#[derive(Debug, Error)] -pub enum HtmlError { - /// Error occurred during Markdown conversion - #[error("Markdown conversion error: {0}")] - MarkdownConversionError(String), - /// Error occurred during template rendering - #[error("Template rendering error: {0}")] - TemplateRenderingError(String), - /// Error occurred during HTML minification - #[error("Minification error: {0}")] - MinificationError(String), - /// Error occurred during SEO optimization - #[error("SEO optimization error: {0}")] - SeoError(String), - /// Error occurred during accessibility enhancements - #[error("Accessibility error: {0}")] - AccessibilityError(String), +/// Get the current version of the library +pub fn version() -> &'static str { + env!("CARGO_PKG_VERSION") +} + +/// Get the minimum supported Rust version +pub fn min_rust_version() -> &'static str { + env!("CARGO_PKG_RUST_VERSION") } /// Result type for HTML generation pub type Result = std::result::Result; + +#[derive(Default)] +/// Builder for `HtmlConfig` to customize HTML generation options. +#[derive(Debug)] +pub struct HtmlConfigBuilder { + config: HtmlConfig, +} + +impl HtmlConfigBuilder { + /// Create a new `HtmlConfigBuilder` with default options. + pub fn new() -> Self { + Self::default() + } + + /// Enable or disable syntax highlighting for code blocks. + /// If enabled but no theme is provided, defaults to "github" theme. + pub fn with_syntax_highlighting( + mut self, + enable: bool, + theme: Option, + ) -> Self { + self.config.enable_syntax_highlighting = enable; + self.config.syntax_theme = if enable { + theme.or_else(|| Some("github".to_string())) + } else { + None + }; + self + } + + /// Set the language for generated content. + /// Only accepts valid language codes (e.g., "en-GB", "fr-FR"). + pub fn with_language( + mut self, + language: impl Into, + ) -> Self { + let lang = language.into(); + if lang.contains('-') && lang.len() >= 4 { + self.config.language = lang; + } + self + } + + /// Enable or disable minification of the generated HTML output. + pub fn build(self) -> HtmlConfig { + self.config + } + + /// Enable or disable minification of the generated HTML output. + pub fn with_minification(mut self, enable: bool) -> Self { + self.config.minify_output = enable; + self + } + + /// Enable or disable automatic addition of ARIA attributes for accessibility. + pub fn with_aria_attributes(mut self, enable: bool) -> Self { + self.config.add_aria_attributes = enable; + self + } + + /// Enable or disable generation of structured data (JSON-LD). + pub fn with_structured_data(mut self, enable: bool) -> Self { + self.config.generate_structured_data = enable; + self + } + + /// Set the maximum size (in bytes) for input content. + /// Enforces a minimum size of 1KB. + pub fn with_max_input_size(mut self, size: usize) -> Self { + self.config.max_input_size = size.max(1024); // Minimum 1KB + self + } + + /// Enable or disable generation of table of contents. + pub fn with_toc(mut self, enable: bool) -> Self { + self.config.generate_toc = enable; + self + } +} + +impl HtmlConfig { + /// Create a new `HtmlConfig` with default options. + pub fn builder() -> HtmlConfigBuilder { + HtmlConfigBuilder::default() + } + + /// Check if syntax highlighting is enabled for code blocks. + /// + /// When enabled, code blocks will be syntax highlighted using the configured theme. + pub fn is_syntax_highlighting_enabled(&self) -> bool { + self.enable_syntax_highlighting + } + + /// Get the configured syntax highlighting theme. + /// + /// Returns the theme name if syntax highlighting is enabled, None otherwise. + pub fn get_syntax_theme(&self) -> Option<&str> { + self.syntax_theme.as_deref() + } + + /// Check if HTML minification is enabled. + /// + /// When enabled, unnecessary whitespace and comments will be removed from the output HTML. + pub fn is_minification_enabled(&self) -> bool { + self.minify_output + } + + /// Check if ARIA attributes generation is enabled. + /// + /// When enabled, appropriate ARIA attributes will be automatically added to HTML elements + /// to improve accessibility. + pub fn are_aria_attributes_enabled(&self) -> bool { + self.add_aria_attributes + } + + /// Check if structured data (JSON-LD) generation is enabled. + /// + /// When enabled, structured data will be generated in JSON-LD format + /// to improve SEO. + pub fn is_structured_data_enabled(&self) -> bool { + self.generate_structured_data + } + + /// Check if table of contents generation is enabled. + /// + /// When enabled, a table of contents will be generated from the document headings. + pub fn is_toc_enabled(&self) -> bool { + self.generate_toc + } + + /// Get the configured language for content generation. + /// + /// Returns the language code (e.g., "en-GB", "fr-FR") that will be used + /// in lang attributes and meta tags. + pub fn get_language(&self) -> &str { + &self.language + } + + /// Get the configured maximum input size in bytes. + /// + /// Returns the maximum allowed size for input content. Default is 5MB. + pub fn get_max_input_size(&self) -> usize { + self.max_input_size + } +} + +#[cfg(test)] +mod tests { + use super::*; + + // HtmlConfig Tests + mod config_tests { + use super::*; + use crate::constants::*; + + #[test] + fn test_default_config() { + let config = HtmlConfig::default(); + assert!(config.enable_syntax_highlighting); + assert_eq!(config.syntax_theme, Some("github".to_string())); + assert!(!config.minify_output); + assert!(config.add_aria_attributes); + assert!(!config.generate_structured_data); + assert_eq!(config.max_input_size, DEFAULT_MAX_INPUT_SIZE); + assert_eq!(config.language, DEFAULT_LANGUAGE); + assert!(!config.generate_toc); + } + + #[test] + fn test_config_equality() { + let config1 = HtmlConfig::default(); + let config2 = HtmlConfig::default(); + assert_eq!(config1, config2); + } + + #[test] + fn test_config_clone() { + let config1 = HtmlConfig::default(); + let config2 = config1.clone(); + assert_eq!(config1, config2); + } + + #[test] + fn test_config_debug() { + let config = HtmlConfig::default(); + let debug_string = format!("{:?}", config); + assert!(debug_string.contains("enable_syntax_highlighting")); + assert!(debug_string.contains("syntax_theme")); + assert!(debug_string.contains("minify_output")); + } + } + + // HtmlConfigBuilder Tests + mod builder_tests { + use super::*; + + #[test] + fn test_builder_new() { + let builder = HtmlConfigBuilder::new(); + let config = builder.build(); + assert_eq!(config, HtmlConfig::default()); + } + + #[test] + fn test_builder_with_syntax_highlighting() { + let config = HtmlConfigBuilder::new() + .with_syntax_highlighting(false, None) + .build(); + assert!(!config.enable_syntax_highlighting); + assert_eq!(config.syntax_theme, None); + } + + #[test] + fn test_builder_with_custom_theme() { + let config = HtmlConfigBuilder::new() + .with_syntax_highlighting( + true, + Some("dracula".to_string()), + ) + .build(); + assert!(config.enable_syntax_highlighting); + assert_eq!( + config.syntax_theme, + Some("dracula".to_string()) + ); + } + + #[test] + fn test_builder_with_language() { + let config = + HtmlConfigBuilder::new().with_language("fr-FR").build(); + assert_eq!(config.language, "fr-FR"); + } + + #[test] + fn test_builder_with_valid_languages() { + let valid_langs = ["en-GB", "fr-FR", "de-DE", "zh-CN"]; + for lang in valid_langs { + let config = HtmlConfigBuilder::new() + .with_language(lang) + .build(); + assert_eq!(config.language, lang); + } + } + + #[test] + fn test_builder_with_more_invalid_languages() { + let invalid_langs = ["en", "f", "", "fr_FR"]; + for lang in invalid_langs { + let config = HtmlConfigBuilder::new() + .with_language(lang) + .build(); + assert_eq!(config.language, "en-GB"); // should keep default + } + } + + #[test] + fn test_builder_chaining() { + let config = HtmlConfigBuilder::new() + .with_syntax_highlighting( + true, + Some("monokai".to_string()), + ) + .with_language("es-ES") + .build(); + + assert!(config.enable_syntax_highlighting); + assert_eq!( + config.syntax_theme, + Some("monokai".to_string()) + ); + assert_eq!(config.language, "es-ES"); + } + + #[test] + fn test_builder_debug() { + let builder = HtmlConfigBuilder::new(); + let debug_string = format!("{:?}", builder); + assert!(debug_string.contains("HtmlConfigBuilder")); + } + + #[test] + fn test_builder_with_invalid_language() { + let config = HtmlConfigBuilder::new() + .with_language("fr") // too short + .build(); + assert_eq!(config.language, "en-GB"); // should keep default + } + + #[test] + fn test_builder_with_small_input_size() { + let config = HtmlConfigBuilder::new() + .with_max_input_size(100) // less than minimum + .build(); + assert_eq!(config.max_input_size, 1024); // should use minimum + } + + #[test] + fn test_builder_all_options() { + let config = HtmlConfigBuilder::new() + .with_syntax_highlighting( + true, + Some("monokai".to_string()), + ) + .with_minification(true) + .with_aria_attributes(false) + .with_structured_data(true) + .with_max_input_size(1024 * 1024) + .with_language("fr-FR") + .with_toc(true) + .build(); + + assert!(config.enable_syntax_highlighting); + assert_eq!( + config.syntax_theme, + Some("monokai".to_string()) + ); + assert!(config.minify_output); + assert!(!config.add_aria_attributes); + assert!(config.generate_structured_data); + assert_eq!(config.max_input_size, 1024 * 1024); + assert_eq!(config.language, "fr-FR"); + assert!(config.generate_toc); + } + + #[test] + fn test_all_config_getters() { + let config = HtmlConfig::default(); + assert!(!config.is_minification_enabled()); + assert!(config.are_aria_attributes_enabled()); + assert!(!config.is_structured_data_enabled()); + assert!(!config.is_toc_enabled()); + assert_eq!(config.get_language(), "en-GB"); + assert_eq!(config.get_max_input_size(), 5 * 1024 * 1024); + } + } + + // Constants Tests + mod constants_tests { + use super::*; + + #[test] + fn test_default_max_input_size() { + assert_eq!( + constants::DEFAULT_MAX_INPUT_SIZE, + 5 * 1024 * 1024 + ); + } + + #[test] + fn test_default_language() { + assert_eq!(constants::DEFAULT_LANGUAGE, "en-GB"); + } + + #[test] + fn test_default_syntax_theme() { + assert_eq!(constants::DEFAULT_SYNTAX_THEME, "github"); + } + } + + // Version Information Tests + mod version_tests { + use super::*; + + #[test] + fn test_version() { + let v = version(); + assert!(!v.is_empty()); + assert!(v.split('.').count() >= 2); + } + + #[test] + fn test_min_rust_version() { + let v = min_rust_version(); + assert!(!v.is_empty()); + assert!(v.split('.').count() >= 2); + } + } + + // Config Factory Method Tests + mod config_factory_tests { + use super::*; + + #[test] + fn test_config_builder_factory() { + let config = HtmlConfig::builder().build(); + assert_eq!(config, HtmlConfig::default()); + } + + #[test] + fn test_config_custom_build() { + let config = HtmlConfig::builder() + .with_syntax_highlighting( + true, + Some("tomorrow".to_string()), + ) + .with_language("de-DE") + .build(); + + assert!(config.enable_syntax_highlighting); + assert_eq!( + config.syntax_theme, + Some("tomorrow".to_string()) + ); + assert_eq!(config.language, "de-DE"); + } + } + + // Result Type Tests + mod result_tests { + use super::*; + + #[test] + fn test_result_ok() { + let result: Result = Ok(42); + assert!(result.is_ok()); + assert_eq!(result.unwrap(), 42); + } + + #[test] + fn test_result_err() { + let error = + HtmlError::InvalidInput("test error".to_string()); + let result: Result = Err(error); + assert!(result.is_err()); + assert!(matches!( + result.unwrap_err(), + HtmlError::InvalidInput(_) + )); + } + } + + // Module Re-exports Tests + mod reexport_tests { + use super::*; + + #[test] + fn test_accessibility_reexports() { + // Verify that the re-exported functions exist + // We don't need to test their functionality here + let _add_aria = add_aria_attributes; + let _validate = validate_wcag; + } + + #[test] + fn test_generator_reexports() { + let _gen_html = generate_html; + } + + #[test] + fn test_performance_reexports() { + let _async_gen = async_generate_html; + let _minify = minify_html; + } + + #[test] + fn test_seo_reexports() { + let _gen_meta = generate_meta_tags; + let _gen_struct = generate_structured_data; + } + + #[test] + fn test_utils_reexports() { + let _extract = extract_front_matter; + let _format = format_header_with_id_class; + } + } +} diff --git a/src/performance.rs b/src/performance.rs index 9457ab8..7818537 100644 --- a/src/performance.rs +++ b/src/performance.rs @@ -59,10 +59,9 @@ fn default_minify_cfg() -> Cfg { pub fn minify_html(file_path: &Path) -> Result { // Read the file content let content = fs::read_to_string(file_path).map_err(|e| { - HtmlError::MinificationError(format!( - "Failed to read file: {}", - e - )) + HtmlError::MinificationError( + format!("Failed to read file: {}", e).into(), + ) })?; // Minify the content @@ -114,7 +113,13 @@ pub async fn async_generate_html(markdown: &str) -> Result { Ok(markdown_to_html(&markdown, &options)) }) .await - .map_err(|e| HtmlError::MarkdownConversionError(e.to_string()))? + .map_err(|e| HtmlError::MarkdownConversion { + message: "Failed to generate HTML asynchronously".to_string(), + source: Some(std::io::Error::new( + std::io::ErrorKind::Other, + e.to_string(), + )), + })? } /// Synchronously generate HTML from Markdown. From dd193933b20a7c714f2569ffb9e22c2688c264b4 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 18:28:41 +0000 Subject: [PATCH 04/34] fix(html-generator): :bug: fix lint issues --- src/lib.rs | 18 ++++++++++++------ src/performance.rs | 7 ++++--- 2 files changed, 16 insertions(+), 9 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index d46b9e4..29be79e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -554,9 +554,13 @@ mod tests { #[test] fn test_result_ok() { - let result: Result = Ok(42); + let value = 42; + let result: Result = Ok(value); assert!(result.is_ok()); - assert_eq!(result.unwrap(), 42); + match result { + Ok(val) => assert_eq!(val, 42), + Err(_) => panic!("Expected Ok value"), + } } #[test] @@ -565,10 +569,12 @@ mod tests { HtmlError::InvalidInput("test error".to_string()); let result: Result = Err(error); assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::InvalidInput(_) - )); + match result { + Ok(_) => panic!("Expected Err value"), + Err(e) => { + assert!(matches!(e, HtmlError::InvalidInput(_))) + } + } } } diff --git a/src/performance.rs b/src/performance.rs index 7818537..2dfc18c 100644 --- a/src/performance.rs +++ b/src/performance.rs @@ -59,9 +59,10 @@ fn default_minify_cfg() -> Cfg { pub fn minify_html(file_path: &Path) -> Result { // Read the file content let content = fs::read_to_string(file_path).map_err(|e| { - HtmlError::MinificationError( - format!("Failed to read file: {}", e).into(), - ) + HtmlError::MinificationError(format!( + "Failed to read file: {}", + e + )) })?; // Minify the content From 61ec3ffbb80779678788359a4ac1d08f8bffd9ea Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 18:39:58 +0000 Subject: [PATCH 05/34] ci(html-generator): :bug: fix coverage github action --- .github/workflows/coverage.yml | 55 ++++++++-------------------------- 1 file changed, 13 insertions(+), 42 deletions(-) diff --git a/.github/workflows/coverage.yml b/.github/workflows/coverage.yml index da0dce7..7307f44 100644 --- a/.github/workflows/coverage.yml +++ b/.github/workflows/coverage.yml @@ -1,61 +1,32 @@ name: 📶 Coverage -on: - push: - branches: - - main - pull_request: - -env: - CARGO_TERM_COLOR: always +on: [push] jobs: - coverage: - name: Code Coverage + lint: runs-on: ubuntu-latest - env: - CARGO_INCREMENTAL: "0" - RUSTFLAGS: "-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests" - RUSTDOCFLAGS: "-Zprofile -Ccodegen-units=1 -Cinline-threshold=0 -Clink-dead-code -Coverflow-checks=off -Cpanic=abort -Zpanic_abort_tests" - steps: - # Checkout the repository - name: Checkout repository uses: actions/checkout@v4 - # Setup Rust nightly - name: Install Rust uses: actions-rs/toolchain@v1 - id: toolchain with: - toolchain: nightly + toolchain: stable override: true - # Configure cache for Cargo - - name: Cache Cargo registry, index - uses: actions/cache@v4 - id: cache-cargo - with: - path: | - ~/.cargo/registry - ~/.cargo/bin - ~/.cargo/git - key: linux-${{ steps.toolchain.outputs.rustc_hash }}-rust-cov-${{ hashFiles('**/Cargo.lock') }} - - # Run tests with all features - - name: Test (cargo test) - uses: actions-rs/cargo@v1 - with: - command: test - args: "--workspace" + - name: Install Cargo Tarpaulin + run: cargo install cargo-tarpaulin - # Install grcov - - uses: actions-rs/grcov@v0.1 - id: coverage + - name: Run tests with coverage + run: cargo tarpaulin --out Lcov --all-features --no-fail-fast + env: + CARGO_INCREMENTAL: '0' + RUSTFLAGS: '-Ccodegen-units=1 -Clink-dead-code -Coverflow-checks=off' + RUSTDOCFLAGS: '' - # Upload to Codecov.io - - name: Upload to Codecov.io + - name: Upload coverage to Codecov uses: codecov/codecov-action@v5 with: token: ${{ secrets.CODECOV_TOKEN }} - file: ${{ steps.coverage.outputs.report }} \ No newline at end of file + files: lcov.info From dffb22a09c1ed6bbcf2307a5fad9f551fccc67aa Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Tue, 26 Nov 2024 18:59:03 +0000 Subject: [PATCH 06/34] fix(html-generator): :bug: Address the unused-results errors --- benches/html_benchmark.rs | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/benches/html_benchmark.rs b/benches/html_benchmark.rs index d8c1f98..8720f6a 100644 --- a/benches/html_benchmark.rs +++ b/benches/html_benchmark.rs @@ -14,7 +14,7 @@ fn benchmark_generate_html(c: &mut Criterion) { let markdown_input = r#"# Benchmark Heading This is a test content for benchmarking HTML generation."#; let config = html_generator::HtmlConfig::default(); - c.bench_function("generate_html", |b| { + let _ = c.bench_function("generate_html", |b| { b.iter(|| generate_html(black_box(markdown_input), &config)) }); } @@ -24,21 +24,21 @@ fn benchmark_minify_html(c: &mut Criterion) { r#"

Test

"#; let temp_file = tempfile::NamedTempFile::new().unwrap(); std::fs::write(temp_file.path(), html_input).unwrap(); - c.bench_function("minify_html", |b| { + let _ = c.bench_function("minify_html", |b| { b.iter(|| minify_html(black_box(temp_file.path()))) }); } fn benchmark_add_aria_attributes(c: &mut Criterion) { let html_input = r#""#; - c.bench_function("add_aria_attributes", |b| { + let _ = c.bench_function("add_aria_attributes", |b| { b.iter(|| add_aria_attributes(black_box(html_input))) }); } fn benchmark_generate_meta_tags(c: &mut Criterion) { let html_input = r#"Page Title

Content

"#; - c.bench_function("generate_meta_tags", |b| { + let _ = c.bench_function("generate_meta_tags", |b| { b.iter(|| generate_meta_tags(black_box(html_input))) }); } @@ -49,7 +49,7 @@ title: Test --- # Content This is the main content."#; - c.bench_function("extract_front_matter", |b| { + let _ = c.bench_function("extract_front_matter", |b| { b.iter(|| extract_front_matter(black_box(input))) }); } From 92dd6f52e4e5677e4df38586232d7c0b90a0472e Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Thu, 28 Nov 2024 22:20:49 +0000 Subject: [PATCH 07/34] refactor(html-generator): :art: clean up and refactoring --- Cargo.toml | 27 +- benches/html_benchmark.rs | 3 +- build.rs | 10 +- examples/accessibility_example.rs | 99 +- examples/error_example.rs | 6 +- examples/lib_example.rs | 21 +- examples/seo_example.rs | 158 ++- src/accessibility.rs | 1629 ++++++++++++++++++++--------- src/error.rs | 39 +- src/generator.rs | 4 +- src/lib.rs | 71 +- src/performance.rs | 521 +++++---- src/seo.rs | 842 +++++++++------ src/utils.rs | 138 ++- 14 files changed, 2330 insertions(+), 1238 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index e6e56da..946729e 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -67,16 +67,18 @@ path = "src/lib.rs" [dependencies] # Dependencies required for building and running the project. +cfg = "0.9.0" comrak = "0.31.0" -lazy_static = "1.5" +lazy_static = "1.5.0" mdx-gen = "0.0.1" -minify-html = "0.15" -once_cell = "1.20" +minify-html = "0.15.0" +once_cell = "1.20.2" regex = "1.11.1" -scraper = "0.21" -tempfile = "3.13" -thiserror = "2.0" -tokio = { version = "1.40", features = ["full"] } +scraper = "0.21.0" +serde_json = "1.0.133" +tempfile = "3.14.0" +thiserror = "2.0.3" +tokio = { version = "1.41.1", features = ["full"] } # ----------------------------------------------------------------------------- # Build Dependencies @@ -84,7 +86,7 @@ tokio = { version = "1.40", features = ["full"] } [build-dependencies] # Dependencies for build scripts. -version_check = "0.9.4" +version_check = "0.9.5" # ----------------------------------------------------------------------------- # Development Dependencies @@ -93,14 +95,7 @@ version_check = "0.9.4" [dev-dependencies] # Dependencies required for testing and development. criterion = "0.5" - -# ----------------------------------------------------------------------------- -# Examples -# ----------------------------------------------------------------------------- - -# [[example]] -# name = "error_example" -# path = "examples/error_example.rs" +test-case = "3.3.1" # ----------------------------------------------------------------------------- diff --git a/benches/html_benchmark.rs b/benches/html_benchmark.rs index 8720f6a..a14df4c 100644 --- a/benches/html_benchmark.rs +++ b/benches/html_benchmark.rs @@ -1,4 +1,3 @@ -// benches/html_benchmark.rs #![allow(missing_docs)] use criterion::{ @@ -32,7 +31,7 @@ fn benchmark_minify_html(c: &mut Criterion) { fn benchmark_add_aria_attributes(c: &mut Criterion) { let html_input = r#""#; let _ = c.bench_function("add_aria_attributes", |b| { - b.iter(|| add_aria_attributes(black_box(html_input))) + b.iter(|| add_aria_attributes(black_box(html_input), None)) }); } diff --git a/build.rs b/build.rs index db9e681..0bedcdb 100644 --- a/build.rs +++ b/build.rs @@ -46,11 +46,9 @@ use std::process; fn main() { let min_version = "1.56"; - match version_check::is_min_version(min_version) { - Some(true) => {} - _ => { - eprintln!("'fd' requires Rustc version >= {}", min_version); - process::exit(1); - } + if version_check::is_min_version(min_version) == Some(true) { + } else { + eprintln!("'fd' requires Rustc version >= {}", min_version); + process::exit(1); } } diff --git a/examples/accessibility_example.rs b/examples/accessibility_example.rs index 80329e0..68fa449 100644 --- a/examples/accessibility_example.rs +++ b/examples/accessibility_example.rs @@ -1,9 +1,10 @@ // src/examples/accessibility_example.rs #![allow(missing_docs)] +use html_generator::accessibility::validate_wcag; use html_generator::{ - accessibility::AccessibilityError, - accessibility::{add_aria_attributes, validate_wcag}, + accessibility::Error, + accessibility::{add_aria_attributes, AccessibilityConfig}, }; /// Entry point for the html-generator accessibility handling examples. @@ -29,42 +30,37 @@ fn main() -> Result<(), Box> { } /// Demonstrates handling of invalid ARIA attribute errors. -fn aria_attribute_error_example() -> Result<(), AccessibilityError> { +fn aria_attribute_error_example() -> Result<(), Error> { println!("🦀 Invalid ARIA Attribute Example"); println!("---------------------------------------------"); let invalid_html = r#"
Content
"#; - let result = add_aria_attributes(invalid_html); + let result = add_aria_attributes(invalid_html, None); // Add None for default config match result { - Ok(_) => { - println!( - " ❌ Unexpected success in adding ARIA attributes" - ) - } - Err(e) => { - println!( - " ✅ Successfully caught Invalid ARIA Attribute Error: {}", - e - ); - } + Ok(_) => println!(" ❌ Unexpected success in adding ARIA attributes"), + Err(e) => println!(" ✅ Successfully caught Invalid ARIA Attribute Error: {}", e), } Ok(()) } /// Demonstrates handling of WCAG validation errors. -fn wcag_validation_error_example() -> Result<(), AccessibilityError> { +fn wcag_validation_error_example() -> Result<(), Error> { println!("\n🦀 WCAG Validation Error Example"); println!("---------------------------------------------"); let invalid_html = r#""#; // Missing alt text - match validate_wcag(invalid_html) { - Ok(_) => { + let config = AccessibilityConfig::default(); + + match validate_wcag(invalid_html, &config, None) { + // Changed to validate_wcag + Ok(report) => { println!( " ❌ Unexpected success in passing WCAG validation" - ) + ); + println!(" Found {} issues", report.issue_count); } Err(e) => { println!( @@ -78,65 +74,60 @@ fn wcag_validation_error_example() -> Result<(), AccessibilityError> { } /// Demonstrates handling of HTML processing errors. -fn html_processing_error_example() -> Result<(), AccessibilityError> { +fn html_processing_error_example() -> Result<(), Error> { println!("\n🦀 HTML Processing Error Example"); println!("---------------------------------------------"); let malformed_html = "
"; - // Map the error from `add_aria_attributes` to `HtmlError::AccessibilityError` - let updated_html = add_aria_attributes(html).map_err(|e| { - HtmlError::accessibility( - AccessibilityErrorKind::MissingAriaAttributes, - e.to_string(), - None, - ) - })?; + // Map the error from `add_aria_attributes` to `HtmlError::Error` + let updated_html = + add_aria_attributes(html, None).map_err(|e| { + HtmlError::accessibility( + ErrorKind::MissingAriaAttributes, + e.to_string(), + None, + ) + })?; println!("Updated HTML with ARIA attributes: \n{}", updated_html); Ok(()) @@ -87,7 +88,7 @@ fn seo_optimization_example() -> Result<()> { // Use a closure to convert the error type to HtmlError::SeoError, which expects a String let meta_tags = generate_meta_tags(html) .map_err(|e| HtmlError::MinificationError(e.to_string()))?; - let structured_data = generate_structured_data(html) + let structured_data = generate_structured_data(html, None) .map_err(|e| HtmlError::MinificationError(e.to_string()))?; println!("Generated Meta Tags: \n{}", meta_tags); diff --git a/examples/seo_example.rs b/examples/seo_example.rs index abf8062..2fbe836 100644 --- a/examples/seo_example.rs +++ b/examples/seo_example.rs @@ -1,58 +1,156 @@ -// src/examples/seo_example.rs - -#![allow(missing_docs)] +//! SEO functionality examples for the HTML Generator library. +//! +//! This module demonstrates the usage of SEO-related features including: +//! - Meta tag generation +//! - Structured data (JSON-LD) generation +//! - SEO optimization techniques use html_generator::seo::{ - generate_meta_tags, generate_structured_data, + generate_meta_tags, generate_structured_data, MetaTagsBuilder, + StructuredDataConfig, }; use html_generator::HtmlError; +use std::collections::HashMap; + +/// Macro for consistent result handling and error reporting +macro_rules! print_result { + ($result:expr, $type:expr) => { + match $result { + Ok(data) => println!("Generated {}: \n{data}", $type), + Err(error) => { + eprintln!("Failed to generate {}: {error}", $type); + return Err(error); + } + } + }; +} +/// Main entry point for the SEO examples. +/// +/// Runs through various examples demonstrating SEO functionality including +/// meta tag generation and structured data implementation. +/// +/// # Errors +/// +/// Returns an error if any of the example functions fail. fn main() -> Result<(), HtmlError> { println!("\n🧪 html-generator SEO Examples\n"); - generate_meta_tags_example()?; + generate_meta_tags_simple_example()?; + generate_meta_tags_builder_example()?; generate_structured_data_example()?; + generate_structured_data_advanced_example()?; println!("\n🎉 All SEO examples completed successfully!"); + Ok(()) +} +/// Demonstrates basic meta tags generation using the simple API. +/// +/// This example shows how to generate meta tags from HTML content +/// using the `generate_meta_tags` function. +/// +/// # Errors +/// +/// Returns an error if meta tag generation fails. +fn generate_meta_tags_simple_example() -> Result<(), HtmlError> { + println!("🦀 Generate Meta Tags (Simple) Example"); + println!("---------------------------------------------"); + + let html = r#" + + Test Page +

This is a test page.

+ + "#; + + print_result!(generate_meta_tags(html), "Meta Tags"); Ok(()) } -/// Demonstrates the generation of meta tags for SEO purposes. -fn generate_meta_tags_example() -> Result<(), HtmlError> { - println!("🦀 Generate Meta Tags Example"); +/// Demonstrates advanced meta tags generation using the builder pattern. +/// +/// This example shows how to use `MetaTagsBuilder` for more control over +/// meta tag generation. +/// +/// # Errors +/// +/// Returns an error if meta tag generation fails. +fn generate_meta_tags_builder_example() -> Result<(), HtmlError> { + println!("\n🦀 Generate Meta Tags (Builder) Example"); println!("---------------------------------------------"); - let html = r#"Test Page

This is a test page.

"#; - match generate_meta_tags(html) { - Ok(meta_tags) => { - println!("Generated Meta Tags: \n{}", meta_tags); - } - Err(e) => { - println!("Failed to generate meta tags: {}", e); - } - } + let meta_tags = MetaTagsBuilder::new() + .with_title("Test Page") + .with_description("This is a test page.") + .add_meta_tag("keywords", "test,example,seo") + .add_meta_tag("author", "Test Author") + .build()?; + println!("Generated Meta Tags: \n{meta_tags}"); Ok(()) } -/// Demonstrates the generation of structured data (JSON-LD) for SEO purposes. +/// Demonstrates basic structured data generation. +/// +/// This example shows how to generate JSON-LD structured data +/// from HTML content using default configuration. +/// +/// # Errors +/// +/// Returns an error if structured data generation fails. fn generate_structured_data_example() -> Result<(), HtmlError> { println!("\n🦀 Generate Structured Data Example"); println!("---------------------------------------------"); - let html = r#"Test Page

This is a test page.

"#; - match generate_structured_data(html) { - Ok(structured_data) => { - println!( - "Generated Structured Data: \n{}", - structured_data - ); - } - Err(e) => { - println!("Failed to generate structured data: {}", e); - } - } + let html = r#" + + Test Page +

This is a test page.

+ + "#; + + print_result!( + generate_structured_data(html, None), + "Structured Data" + ); + Ok(()) +} + +/// Demonstrates advanced structured data generation with custom configuration. +/// +/// This example shows how to generate JSON-LD structured data with +/// custom types and additional data. +/// +/// # Errors +/// +/// Returns an error if structured data generation fails. +fn generate_structured_data_advanced_example() -> Result<(), HtmlError> +{ + println!("\n🦀 Generate Structured Data (Advanced) Example"); + println!("---------------------------------------------"); + + let html = r#" + + Test Article +

This is a test article.

+ + "#; + + let additional_data = HashMap::from([ + ("author".to_string(), "Test Author".to_string()), + ("datePublished".to_string(), "2024-03-15".to_string()), + ]); + + let config = StructuredDataConfig { + page_type: "Article".to_string(), + additional_types: vec!["WebPage".to_string()], + additional_data: Some(additional_data), + }; + print_result!( + generate_structured_data(html, Some(config)), + "Advanced Structured Data" + ); Ok(()) } diff --git a/src/accessibility.rs b/src/accessibility.rs index 024a4ed..b66a4c7 100644 --- a/src/accessibility.rs +++ b/src/accessibility.rs @@ -1,68 +1,243 @@ //! Accessibility-related functionality for HTML processing. //! -//! This module provides functions for improving the accessibility of HTML content, including adding ARIA attributes and validating against WCAG guidelines. +//! This module provides comprehensive tools for improving HTML accessibility through: +//! - Automated ARIA attribute management +//! - WCAG 2.1 compliance validation +//! - Accessibility issue detection and correction +//! +//! # WCAG Compliance +//! +//! This module implements checks for WCAG 2.1 compliance across three levels: +//! - Level A (minimum level of conformance) +//! - Level AA (addresses major accessibility barriers) +//! - Level AAA (highest level of accessibility conformance) +//! +//! For detailed information about WCAG guidelines, see: +//! +//! +//! # Limitations +//! +//! While this module provides automated checks, some accessibility aspects require +//! manual review, including: +//! - Semantic correctness of ARIA labels +//! - Meaningful alternative text for images +//! - Logical heading structure +//! - Color contrast ratios +//! +//! # Examples +//! +//! ```rust +//! use html_generator::accessibility::{add_aria_attributes, validate_wcag, WcagLevel}; +//! +//! use html_generator::accessibility::AccessibilityConfig; +//! fn main() -> Result<(), Box> { +//! let html = r#""#; +//! +//! // Add ARIA attributes automatically +//! let enhanced_html = add_aria_attributes(html, None)?; +//! +//! // Validate against WCAG AA level +//! let config = AccessibilityConfig::default(); +//! validate_wcag(&enhanced_html, &config, None)?; +//! +//! Ok(()) +//! } +//! ``` +use crate::accessibility::utils::get_missing_required_aria_properties; +use crate::accessibility::utils::is_valid_aria_role; +use crate::accessibility::utils::is_valid_language_code; use once_cell::sync::Lazy; use regex::Regex; use scraper::{Html, Selector}; use std::collections::HashSet; use thiserror::Error; -/// Maximum size of HTML input in bytes (1MB) -const MAX_HTML_SIZE: usize = 1_000_000; +/// Constants used throughout the accessibility module +pub mod constants { + /// Maximum size of HTML input in bytes (1MB) + pub const MAX_HTML_SIZE: usize = 1_000_000; + + /// Default ARIA role for navigation elements + pub const DEFAULT_NAV_ROLE: &str = "navigation"; + + /// Default ARIA role for buttons + pub const DEFAULT_BUTTON_ROLE: &str = "button"; + + /// Default ARIA role for forms + pub const DEFAULT_FORM_ROLE: &str = "form"; + + /// Default ARIA role for inputs + pub const DEFAULT_INPUT_ROLE: &str = "textbox"; +} + +use constants::{ + DEFAULT_BUTTON_ROLE, DEFAULT_INPUT_ROLE, DEFAULT_NAV_ROLE, + MAX_HTML_SIZE, +}; + +/// WCAG Conformance Levels +#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] +pub enum WcagLevel { + /// Level A: Minimum level of conformance + /// Essential accessibility features that must be supported + A, + + /// Level AA: Addresses major accessibility barriers + /// Standard level of conformance for most websites + AA, + + /// Level AAA: Highest level of accessibility conformance + /// Includes additional enhancements and specialized features + AAA, +} + +/// Types of accessibility issues that can be detected +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum IssueType { + /// Missing alternative text for images + MissingAltText, + /// Improper heading structure + HeadingStructure, + /// Missing form labels + MissingLabels, + /// Invalid ARIA attributes + InvalidAria, + /// Color contrast issues + ColorContrast, + /// Keyboard navigation issues + KeyboardNavigation, + /// Missing or invalid language declarations + LanguageDeclaration, +} /// Enum to represent possible accessibility-related errors. #[derive(Debug, Error)] -pub enum AccessibilityError { +pub enum Error { /// Error indicating an invalid ARIA attribute. - #[error("Invalid ARIA Attribute: {0}")] - InvalidAriaAttribute(String), + #[error("Invalid ARIA Attribute '{attribute}': {message}")] + InvalidAriaAttribute { + /// The name of the invalid attribute + attribute: String, + /// Description of the error + message: String, + }, /// Error indicating failure to validate HTML against WCAG guidelines. - #[error("WCAG Validation Error: {0}")] - WcagValidationError(String), - - /// Error indicating a failure in processing HTML for accessibility. - #[error("HTML Processing Error: {0}")] - HtmlProcessingError(String), + #[error("WCAG {level} Validation Error: {message}")] + WcagValidationError { + /// WCAG conformance level where the error occurred + level: WcagLevel, + /// Description of the error + message: String, + /// Specific WCAG guideline reference + guideline: Option, + }, /// Error indicating the HTML input is too large to process. - #[error("HTML Input Too Large: {0}")] - HtmlTooLarge(usize), + #[error( + "HTML Input Too Large: size {size} exceeds maximum {max_size}" + )] + HtmlTooLarge { + /// Actual size of the input + size: usize, + /// Maximum allowed size + max_size: usize, + }, + + /// Error indicating a failure in processing HTML for accessibility. + #[error("HTML Processing Error: {message}")] + HtmlProcessingError { + /// Description of the processing error + message: String, + /// Source of the error, if available + source: Option>, + }, /// Error indicating malformed HTML input. - #[error("Malformed HTML: {0}")] - MalformedHtml(String), + #[error("Malformed HTML: {message}")] + MalformedHtml { + /// Description of the HTML issue + message: String, + /// The problematic HTML fragment, if available + fragment: Option, + }, } -/// Result type alias for convenience. -pub type Result = std::result::Result; - -static BUTTON_SELECTOR: Lazy = Lazy::new(|| { - Selector::parse("button:not([aria-label])") - .expect("Failed to create button selector") -}); - -static NAV_SELECTOR: Lazy = Lazy::new(|| { - Selector::parse("nav:not([aria-label])") - .expect("Failed to create nav selector") -}); +/// Result type alias for accessibility operations. +pub type Result = std::result::Result; + +/// Structure representing an accessibility issue found in the HTML +#[derive(Debug, Clone)] +pub struct Issue { + /// Type of accessibility issue + pub issue_type: IssueType, + /// Description of the issue + pub message: String, + /// WCAG guideline reference, if applicable + pub guideline: Option, + /// HTML element where the issue was found + pub element: Option, + /// Suggested fix for the issue + pub suggestion: Option, +} -static FORM_SELECTOR: Lazy = Lazy::new(|| { - Selector::parse("form:not([aria-labelledby])") - .expect("Failed to create form selector") -}); +/// Helper function to create a `Selector`, returning an `Option` on failure. +fn try_create_selector(selector: &str) -> Option { + match Selector::parse(selector) { + Ok(s) => Some(s), + Err(e) => { + eprintln!( + "Failed to create selector '{}': {}", + selector, e + ); + None + } + } +} -static INPUT_REGEX: Lazy = Lazy::new(|| { - Regex::new(r#"]*>"#).expect("Failed to create input regex") -}); +/// Helper function to create a `Regex`, returning an `Option` on failure. +fn try_create_regex(pattern: &str) -> Option { + match Regex::new(pattern) { + Ok(r) => Some(r), + Err(e) => { + eprintln!("Failed to create regex '{}': {}", pattern, e); + None + } + } +} -static ARIA_SELECTOR: Lazy = Lazy::new(|| { - Selector::parse( - "[aria-label], [aria-labelledby], [aria-describedby], [aria-hidden], [aria-expanded], [aria-haspopup], [aria-controls], [aria-pressed], [aria-checked], [aria-current], [aria-disabled], [aria-dropeffect], [aria-grabbed], [aria-haspopup], [aria-invalid], [aria-live], [aria-owns], [aria-relevant], [aria-required], [aria-role], [aria-selected], [aria-valuemax], [aria-valuemin], [aria-valuenow], [aria-valuetext]" - ).expect("Failed to create ARIA selector") +/// Static selectors for HTML elements and ARIA attributes +static BUTTON_SELECTOR: Lazy> = + Lazy::new(|| try_create_selector("button:not([aria-label])")); + +/// Selector for navigation elements without ARIA attributes +static NAV_SELECTOR: Lazy> = + Lazy::new(|| try_create_selector("nav:not([aria-label])")); + +/// Selector for form elements without ARIA attributes +static FORM_SELECTOR: Lazy> = + Lazy::new(|| try_create_selector("form:not([aria-labelledby])")); + +/// Regex for finding input elements +static INPUT_REGEX: Lazy> = + Lazy::new(|| try_create_regex(r"]*>")); + +/// Comprehensive selector for all ARIA attributes +static ARIA_SELECTOR: Lazy> = Lazy::new(|| { + try_create_selector(concat!( + "[aria-label], [aria-labelledby], [aria-describedby], ", + "[aria-hidden], [aria-expanded], [aria-haspopup], ", + "[aria-controls], [aria-pressed], [aria-checked], ", + "[aria-current], [aria-disabled], [aria-dropeffect], ", + "[aria-grabbed], [aria-invalid], [aria-live], ", + "[aria-owns], [aria-relevant], [aria-required], ", + "[aria-role], [aria-selected], [aria-valuemax], ", + "[aria-valuemin], [aria-valuenow], [aria-valuetext]" + )) }); +/// Set of valid ARIA attributes static VALID_ARIA_ATTRIBUTES: Lazy> = Lazy::new(|| { [ @@ -79,7 +254,6 @@ static VALID_ARIA_ATTRIBUTES: Lazy> = "aria-disabled", "aria-dropeffect", "aria-grabbed", - "aria-haspopup", "aria-invalid", "aria-live", "aria-owns", @@ -93,85 +267,408 @@ static VALID_ARIA_ATTRIBUTES: Lazy> = "aria-valuetext", ] .iter() - .cloned() + .copied() .collect() }); +/// Color contrast requirements for different WCAG levels +// static COLOR_CONTRAST_RATIOS: Lazy> = Lazy::new(|| { +// let mut m = HashMap::new(); +// m.insert(WcagLevel::A, 3.0); // Minimum contrast for Level A +// m.insert(WcagLevel::AA, 4.5); // Enhanced contrast for Level AA +// m.insert(WcagLevel::AAA, 7.0); // Highest contrast for Level AAA +// m +// }); +/// +/// Set of elements that must have labels +// static LABELABLE_ELEMENTS: Lazy> = Lazy::new(|| { +// [ +// "input", "select", "textarea", "button", "meter", +// "output", "progress", "canvas" +// ].iter().copied().collect() +// }); +/// +/// Selector for finding headings +// static HEADING_SELECTOR: Lazy = Lazy::new(|| { +// Selector::parse("h1, h2, h3, h4, h5, h6") +// .expect("Failed to create heading selector") +// }); +/// +/// Selector for finding images +// static IMAGE_SELECTOR: Lazy = Lazy::new(|| { +// Selector::parse("img").expect("Failed to create image selector") +// }); +/// Configuration for accessibility validation +#[derive(Debug, Copy, Clone)] +pub struct AccessibilityConfig { + /// WCAG conformance level to validate against + pub wcag_level: WcagLevel, + /// Maximum allowed heading level jump (e.g., 1 means no skipping levels) + pub max_heading_jump: u8, + /// Minimum required color contrast ratio + pub min_contrast_ratio: f64, + /// Whether to automatically fix issues when possible + pub auto_fix: bool, +} + +impl Default for AccessibilityConfig { + fn default() -> Self { + Self { + wcag_level: WcagLevel::AA, + max_heading_jump: 1, + min_contrast_ratio: 4.5, // WCAG AA standard + auto_fix: true, + } + } +} + +/// A comprehensive accessibility check result +#[derive(Debug)] +pub struct AccessibilityReport { + /// List of accessibility issues found + pub issues: Vec, + /// WCAG conformance level checked + pub wcag_level: WcagLevel, + /// Total number of elements checked + pub elements_checked: usize, + /// Number of issues found + pub issue_count: usize, + /// Time taken for the check (in milliseconds) + pub check_duration_ms: u64, +} + /// Add ARIA attributes to HTML for improved accessibility. /// -/// This function adds ARIA attributes to common elements, such as buttons, forms, -/// navigation elements, and images. +/// This function performs a comprehensive analysis of the HTML content and adds +/// appropriate ARIA attributes to improve accessibility. It handles: +/// - Button labeling +/// - Navigation landmarks +/// - Form controls +/// - Input elements +/// - Dynamic content /// /// # Arguments /// -/// * `html` - A string slice representing the HTML content. +/// * `html` - A string slice representing the HTML content +/// * `config` - Optional configuration for the enhancement process /// /// # Returns /// -/// * `Result` - The modified HTML with ARIA attributes included. +/// * `Result` - The modified HTML with ARIA attributes included /// /// # Errors /// -/// This function will return an error if: -/// * The input HTML is larger than `MAX_HTML_SIZE`. -/// * The HTML cannot be parsed. -/// * There's an error adding ARIA attributes. +/// Returns an error if: +/// * The input HTML is larger than `MAX_HTML_SIZE` +/// * The HTML cannot be parsed +/// * There's an error adding ARIA attributes /// /// # Examples /// -/// ``` -/// use html_generator::accessibility::add_aria_attributes; +/// ```rust +/// use html_generator::accessibility::{add_aria_attributes, AccessibilityConfig}; +/// +/// fn main() -> Result<(), Box> { +/// let html = r#""#; +/// let result = add_aria_attributes(html, None)?; +/// assert!(result.contains(r#"aria-label="Click me""#)); /// -/// let html = r#""#; -/// let result = add_aria_attributes(html); -/// assert!(result.is_ok()); -/// assert!(result.unwrap().contains(r#"aria-label="button""#)); +/// Ok(()) +/// } /// ``` -pub fn add_aria_attributes(html: &str) -> Result { +pub fn add_aria_attributes( + html: &str, + config: Option, +) -> Result { + let config = config.unwrap_or_default(); + if html.len() > MAX_HTML_SIZE { - return Err(AccessibilityError::HtmlTooLarge(html.len())); + return Err(Error::HtmlTooLarge { + size: html.len(), + max_size: MAX_HTML_SIZE, + }); } let mut html_builder = HtmlBuilder::new(html); + // Apply transformations html_builder = add_aria_to_buttons(html_builder)?; html_builder = add_aria_to_navs(html_builder)?; html_builder = add_aria_to_forms(html_builder)?; html_builder = add_aria_to_inputs(html_builder)?; - // Remove invalid ARIA attributes before returning + // Additional transformations for stricter WCAG levels + if matches!(config.wcag_level, WcagLevel::AA | WcagLevel::AAA) { + html_builder = enhance_landmarks(html_builder)?; + html_builder = add_live_regions(html_builder)?; + } + + if matches!(config.wcag_level, WcagLevel::AAA) { + html_builder = enhance_descriptions(html_builder)?; + } + + // Validate and clean up let new_html = remove_invalid_aria_attributes(&html_builder.build()); if !validate_aria(&new_html) { - return Err(AccessibilityError::InvalidAriaAttribute( - "Failed to add valid ARIA attributes.".to_string(), - )); + return Err(Error::InvalidAriaAttribute { + attribute: "multiple".to_string(), + message: "Failed to add valid ARIA attributes".to_string(), + }); } Ok(new_html) } +/// A builder struct for constructing HTML content. +#[derive(Debug, Clone)] +struct HtmlBuilder { + content: String, +} + +impl HtmlBuilder { + /// Creates a new `HtmlBuilder` with the given initial content. + fn new(initial_content: &str) -> Self { + HtmlBuilder { + content: initial_content.to_string(), + } + } + + /// Builds the final HTML content. + fn build(self) -> String { + self.content + } +} + +/// Helper function to count total elements checked during validation +fn count_checked_elements(document: &Html) -> usize { + document.select(&Selector::parse("*").unwrap()).count() +} + +/// Add landmark regions to improve navigation +const fn enhance_landmarks( + html_builder: HtmlBuilder, +) -> Result { + // Implementation for adding landmarks + Ok(html_builder) +} + +/// Add live regions for dynamic content +const fn add_live_regions( + html_builder: HtmlBuilder, +) -> Result { + // Implementation for adding live regions + Ok(html_builder) +} + +/// Enhance element descriptions for better accessibility +const fn enhance_descriptions( + html_builder: HtmlBuilder, +) -> Result { + // Implementation for enhancing descriptions + Ok(html_builder) +} + +/// Check heading structure +fn check_heading_structure(document: &Html, issues: &mut Vec) { + let mut prev_level: Option = None; + + let selector = match Selector::parse("h1, h2, h3, h4, h5, h6") { + Ok(selector) => selector, + Err(e) => { + eprintln!("Failed to parse selector: {}", e); + return; // Skip checking if the selector is invalid + } + }; + + for heading in document.select(&selector) { + let current_level = heading + .value() + .name() + .chars() + .nth(1) + .and_then(|c| c.to_digit(10)) + .and_then(|n| u8::try_from(n).ok()); + + if let Some(current_level) = current_level { + if let Some(prev_level) = prev_level { + if current_level > prev_level + 1 { + issues.push(Issue { + issue_type: IssueType::HeadingStructure, + message: format!( + "Skipped heading level from h{} to h{}", + prev_level, current_level + ), + guideline: Some("WCAG 2.4.6".to_string()), + element: Some(heading.html()), + suggestion: Some( + "Use sequential heading levels".to_string(), + ), + }); + } + } + prev_level = Some(current_level); + } + } +} + +/// Validate HTML against WCAG guidelines with detailed reporting. +/// +/// Performs a comprehensive accessibility check based on WCAG guidelines and +/// provides detailed feedback about any issues found. +/// +/// # Arguments +/// +/// * `html` - The HTML content to validate +/// * `config` - Configuration options for the validation +/// +/// # Returns +/// +/// * `Result` - A detailed report of the accessibility check +/// +/// # Examples +/// +/// ```rust +/// use html_generator::accessibility::{validate_wcag, AccessibilityConfig, WcagLevel}; +/// +/// fn main() -> Result<(), Box> { +/// let html = r#"A descriptive alt text"#; +/// let config = AccessibilityConfig::default(); +/// +/// let report = validate_wcag(html, &config, None)?; +/// println!("Found {} issues", report.issue_count); +/// +/// Ok(()) +/// } +/// ``` +pub fn validate_wcag( + html: &str, + config: &AccessibilityConfig, + disable_checks: Option<&[IssueType]>, +) -> Result { + let start_time = std::time::Instant::now(); + let mut issues = Vec::new(); + let mut elements_checked = 0; + + if html.trim().is_empty() { + return Ok(AccessibilityReport { + issues: Vec::new(), + wcag_level: config.wcag_level, + elements_checked: 0, + issue_count: 0, + check_duration_ms: 0, + }); + } + + let document = Html::parse_document(html); + + if disable_checks + .map_or(true, |d| !d.contains(&IssueType::LanguageDeclaration)) + { + check_language_attributes(&document, &mut issues)?; // Returns Result<()>, so `?` works. + } + + // This function returns `()`, so no `?`. + check_heading_structure(&document, &mut issues); + + elements_checked += count_checked_elements(&document); + + // Explicit error conversion for u64::try_from + let check_duration_ms = u64::try_from( + start_time.elapsed().as_millis(), + ) + .map_err(|err| Error::HtmlProcessingError { + message: "Failed to convert duration to milliseconds" + .to_string(), + source: Some(Box::new(err)), + })?; + + Ok(AccessibilityReport { + issues: issues.clone(), + wcag_level: config.wcag_level, + elements_checked, + issue_count: issues.len(), + check_duration_ms, + }) +} + +/// From implementation for TryFromIntError +impl From for Error { + fn from(err: std::num::TryFromIntError) -> Self { + Error::HtmlProcessingError { + message: "Integer conversion error".to_string(), + source: Some(Box::new(err)), + } + } +} + +/// Display implementation for WCAG levels +impl std::fmt::Display for WcagLevel { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + WcagLevel::A => write!(f, "A"), + WcagLevel::AA => write!(f, "AA"), + WcagLevel::AAA => write!(f, "AAA"), + } + } +} + +/// Internal helper functions for accessibility checks +impl AccessibilityReport { + /// Creates a new accessibility issue + fn add_issue( + issues: &mut Vec, + issue_type: IssueType, + message: impl Into, + guideline: Option, + element: Option, + suggestion: Option, + ) { + issues.push(Issue { + issue_type, + message: message.into(), + guideline, + element, + suggestion, + }); + } +} + /// Add ARIA attributes to button elements. fn add_aria_to_buttons( mut html_builder: HtmlBuilder, ) -> Result { let document = Html::parse_document(&html_builder.content); - for button in document.select(&BUTTON_SELECTOR) { - // Only modify buttons that do not already have an aria-label - if button.value().attr("aria-label").is_none() { - let button_html = button.html(); - let inner_content = button.inner_html(); // Get inner content - let new_button_html = format!( - r#""#, - inner_content - ); - - // Replace original button with the modified one - html_builder.content = html_builder - .content - .replace(&button_html, &new_button_html); + // Safely unwrap the BUTTON_SELECTOR + if let Some(selector) = BUTTON_SELECTOR.as_ref() { + for button in document.select(selector) { + // Check if the button has no aria-label + if button.value().attr("aria-label").is_none() { + let button_html = button.html(); + let inner_content = button.inner_html(); + + // Generate a new button with appropriate aria-label + let new_button_html = if inner_content.trim().is_empty() + { + format!( + r#""#, + DEFAULT_BUTTON_ROLE, inner_content + ) + } else { + format!( + r#""#, + inner_content.trim(), + inner_content + ) + }; + + // Replace the old button HTML with the new one + html_builder.content = html_builder + .content + .replace(&button_html, &new_button_html); + } } } @@ -183,12 +680,20 @@ fn add_aria_to_navs( mut html_builder: HtmlBuilder, ) -> Result { let document = Html::parse_document(&html_builder.content); - for nav in document.select(&NAV_SELECTOR) { - let nav_html = nav.html(); - let new_nav_html = - nav_html.replace(" Result { let document = Html::parse_document(&html_builder.content); - for form in document.select(&FORM_SELECTOR) { - let form_html = form.html(); - let new_form_html = form_html - .replace(" Result { - let mut replacements = Vec::with_capacity( - INPUT_REGEX.captures_iter(&html_builder.content).count(), - ); - - for cap in INPUT_REGEX.captures_iter(&html_builder.content) { - let input_tag = &cap[0]; - if !input_tag.contains("aria-label") { - let new_input_tag = input_tag - .replace(" = Vec::new(); + + for cap in regex.captures_iter(&html_builder.content) { + let input_tag = &cap[0]; + if !input_tag.contains("aria-label") { + let input_type = extract_input_type(input_tag) + .unwrap_or_else(|| "text".to_string()); + let new_input_tag = format!( + r#" bool { - let document = Html::parse_document(html); +/// Extract input type from an input tag. +fn extract_input_type(input_tag: &str) -> Option { + static TYPE_REGEX: Lazy = Lazy::new(|| { + Regex::new(r#"type=["']([^"']+)["']"#) + .expect("Failed to create type regex") + }); - // Iterate over all elements that have ARIA attributes - document - .select(&ARIA_SELECTOR) - .flat_map(|el| el.value().attrs()) - .filter(|(name, _)| name.starts_with("aria-")) - .all(|(name, value)| { - // Ensure the attribute is in the valid list and its value is valid - is_valid_aria_attribute(name, value) - }) + TYPE_REGEX + .captures(input_tag) + .and_then(|cap| cap.get(1)) + .map(|m| m.as_str().to_string()) } -/// Check if an ARIA attribute is valid. -/// -/// This function checks if the given ARIA attribute name and value conform to the ARIA specification. -/// -/// # Arguments -/// -/// * `name` - The name of the ARIA attribute. -/// * `value` - The value of the ARIA attribute. -/// -/// # Returns -/// -/// * `bool` - Returns `true` if the ARIA attribute is valid, otherwise `false`. -fn is_valid_aria_attribute(name: &str, value: &str) -> bool { - if !VALID_ARIA_ATTRIBUTES.contains(name) { - return false; - } +/// Generate a unique ID for form elements. +fn generate_unique_id() -> String { + use std::time::{SystemTime, UNIX_EPOCH}; + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .subsec_nanos(); + format!("aria-{}", nanos) +} - match name { - "aria-hidden" | "aria-expanded" | "aria-pressed" - | "aria-invalid" => ["true", "false"].contains(&value), - _ => !value.is_empty(), +/// Validate ARIA attributes within the HTML. +fn validate_aria(html: &str) -> bool { + let document = Html::parse_document(html); + + if let Some(selector) = ARIA_SELECTOR.as_ref() { + document + .select(selector) + .flat_map(|el| el.value().attrs()) + .filter(|(name, _)| name.starts_with("aria-")) + .all(|(name, value)| is_valid_aria_attribute(name, value)) + } else { + eprintln!("ARIA_SELECTOR failed to initialize."); + false } } -/// Remove invalid ARIA attributes from the HTML. fn remove_invalid_aria_attributes(html: &str) -> String { let document = Html::parse_document(html); - let aria_selector = Selector::parse("[aria-label], [aria-labelledby], [aria-describedby], [aria-hidden], [aria-expanded], [aria-haspopup], [aria-controls], [aria-pressed], [aria-invalid]") - .expect("Failed to create invalid ARIA selector"); let mut new_html = html.to_string(); - for element in document.select(&aria_selector) { - let element_html = element.html(); - let new_element_html = element - .value() - .attrs() - .filter(|(name, value)| { - !name.starts_with("aria-") - || is_valid_aria_attribute(name, value) - }) - .fold(String::new(), |mut acc, (name, value)| { - acc.push_str(&format!(r#" {}="{}""#, name, value)); - acc - }); - - let new_tag = - format!("<{}{}>", element.value().name(), new_element_html); - new_html = new_html.replace(&element_html, &new_tag); + if let Some(selector) = ARIA_SELECTOR.as_ref() { + for element in document.select(selector) { + let element_html = element.html(); + let mut updated_html = element_html.clone(); + + for (attr_name, attr_value) in element.value().attrs() { + if attr_name.starts_with("aria-") + && !is_valid_aria_attribute(attr_name, attr_value) + { + updated_html = updated_html.replace( + &format!(r#" {}="{}""#, attr_name, attr_value), + "", + ); + } + } + + new_html = new_html.replace(&element_html, &updated_html); + } } new_html } -/// Validate HTML against WCAG (Web Content Accessibility Guidelines). -/// -/// This function performs various checks to validate the HTML content against WCAG standards, -/// such as ensuring all images have alt text, proper heading structure, and more. -/// -/// # Arguments -/// -/// * `html` - A string slice that holds the HTML content. -/// -/// # Returns -/// -/// * `Result<()>` - An empty result if validation passes, otherwise an error. -/// -/// # Errors -/// -/// This function will return an error if: -/// * The input HTML is larger than `MAX_HTML_SIZE`. -/// * The HTML fails to meet WCAG guidelines. -/// -/// # Examples -/// -/// ``` -/// use html_generator::accessibility::validate_wcag; -/// -/// let html = r#"A descriptive alt text

Title

Subtitle

"#; -/// let result = validate_wcag(html); -/// assert!(result.is_ok()); -/// ``` -pub fn validate_wcag(html: &str) -> Result<()> { - if html.len() > MAX_HTML_SIZE { - return Err(AccessibilityError::HtmlTooLarge(html.len())); +/// Check if an ARIA attribute is valid. +fn is_valid_aria_attribute(name: &str, value: &str) -> bool { + if !VALID_ARIA_ATTRIBUTES.contains(name) { + return false; // Invalid ARIA attribute name } - let document = Html::parse_document(html); + match name { + "aria-hidden" | "aria-expanded" | "aria-pressed" + | "aria-invalid" => { + matches!(value, "true" | "false") // Only "true" or "false" are valid + } + "aria-level" => value.parse::().is_ok(), // Must be a valid integer + _ => !value.trim().is_empty(), // General check for non-empty values + } +} - check_alt_text(&document)?; - check_heading_structure(&document)?; - check_input_labels(&document)?; +fn check_language_attributes( + document: &Html, + issues: &mut Vec, +) -> Result<()> { + if let Some(html_element) = + document.select(&Selector::parse("html").unwrap()).next() + { + if html_element.value().attr("lang").is_none() { + AccessibilityReport::add_issue( + issues, + IssueType::LanguageDeclaration, + "Missing language declaration on HTML element", + Some("WCAG 3.1.1".to_string()), + Some("".to_string()), + Some("Add lang attribute to HTML element".to_string()), + ); + } + } + for element in document.select(&Selector::parse("[lang]").unwrap()) + { + if let Some(lang) = element.value().attr("lang") { + if !is_valid_language_code(lang) { + AccessibilityReport::add_issue( + issues, + IssueType::LanguageDeclaration, + format!("Invalid language code: {}", lang), + Some("WCAG 3.1.2".to_string()), + Some(element.html()), + Some("Use valid BCP 47 language code".to_string()), + ); + } + } + } Ok(()) } -/// Check for the presence of alt text in images. -fn check_alt_text(document: &Html) -> Result<()> { - let img_selector = Selector::parse("img").map_err(|e| { - AccessibilityError::HtmlProcessingError(e.to_string()) - })?; - if document - .select(&img_selector) - .any(|img| img.value().attr("alt").is_none()) - { - Err(AccessibilityError::WcagValidationError( - "Missing alt text for images.".to_string(), - )) - } else { +/// Helper functions for WCAG validation +impl AccessibilityReport { + /// Check keyboard navigation + pub fn check_keyboard_navigation( + document: &Html, + issues: &mut Vec, + ) -> Result<()> { + let binding = Selector::parse( + "a, button, input, select, textarea, [tabindex]", + ) + .unwrap(); + let interactive_elements = document.select(&binding); + + for element in interactive_elements { + // Check tabindex + if let Some(tabindex) = element.value().attr("tabindex") { + if let Ok(index) = tabindex.parse::() { + if index < 0 { + Self::add_issue( + issues, + IssueType::KeyboardNavigation, + "Negative tabindex prevents keyboard focus", + Some("WCAG 2.1.1".to_string()), + Some(element.html()), + Some( + "Remove negative tabindex value" + .to_string(), + ), + ); + } + } + } + + // Check for click handlers without keyboard equivalents + if element.value().attr("onclick").is_some() + && element.value().attr("onkeypress").is_none() + && element.value().attr("onkeydown").is_none() + { + Self::add_issue( + issues, + IssueType::KeyboardNavigation, + "Click handler without keyboard equivalent", + Some("WCAG 2.1.1".to_string()), + Some(element.html()), + Some("Add keyboard event handlers".to_string()), + ); + } + } Ok(()) } -} - -/// Check heading structure to ensure no levels are skipped. -fn check_heading_structure(document: &Html) -> Result<()> { - let heading_selector = Selector::parse("h1, h2, h3, h4, h5, h6") - .map_err(|e| { - AccessibilityError::HtmlProcessingError(e.to_string()) - })?; - let mut prev_level = 0; - for heading in document.select(&heading_selector) { - let current_level = heading - .value() - .name() - .chars() - .nth(1) - .and_then(|c| c.to_digit(10)) - .ok_or_else(|| { - AccessibilityError::MalformedHtml( - "Invalid heading tag".to_string(), - ) - })?; + /// Check language attributes + pub fn check_language_attributes( + document: &Html, + issues: &mut Vec, + ) -> Result<()> { + // Check html lang attribute + let html_element = + document.select(&Selector::parse("html").unwrap()).next(); + if let Some(element) = html_element { + if element.value().attr("lang").is_none() { + Self::add_issue( + issues, + IssueType::LanguageDeclaration, + "Missing language declaration", + Some("WCAG 3.1.1".to_string()), + Some(element.html()), + Some( + "Add lang attribute to html element" + .to_string(), + ), + ); + } + } - if current_level > prev_level + 1 { - return Err(AccessibilityError::WcagValidationError( - "Improper heading structure (skipping heading levels)." - .to_string(), - )); + // Check for changes in language + let binding = Selector::parse("[lang]").unwrap(); + let text_elements = document.select(&binding); + for element in text_elements { + if let Some(lang) = element.value().attr("lang") { + if !is_valid_language_code(lang) { + Self::add_issue( + issues, + IssueType::LanguageDeclaration, + format!("Invalid language code: {}", lang), + Some("WCAG 3.1.2".to_string()), + Some(element.html()), + Some( + "Use valid BCP 47 language code" + .to_string(), + ), + ); + } + } } - prev_level = current_level; + Ok(()) } - Ok(()) -} + /// Check advanced ARIA usage + pub fn check_advanced_aria( + document: &Html, + issues: &mut Vec, + ) -> Result<()> { + // Check for proper ARIA roles + let binding = Selector::parse("[role]").unwrap(); + let elements_with_roles = document.select(&binding); + for element in elements_with_roles { + if let Some(role) = element.value().attr("role") { + if !is_valid_aria_role(role, &element) { + Self::add_issue( + issues, + IssueType::InvalidAria, + format!( + "Invalid ARIA role '{}' for element", + role + ), + Some("WCAG 4.1.2".to_string()), + Some(element.html()), + Some("Use appropriate ARIA role".to_string()), + ); + } + } + } -/// Check if all form inputs have associated labels. -fn check_input_labels(document: &Html) -> Result<()> { - let input_selector = Selector::parse("input").map_err(|e| { - AccessibilityError::HtmlProcessingError(e.to_string()) - })?; - if document.select(&input_selector).any(|input| { - input.value().attr("aria-label").is_none() - && input.value().attr("id").is_none() - }) { - Err(AccessibilityError::WcagValidationError( - "Form inputs missing associated labels.".to_string(), - )) - } else { + // Check for required ARIA properties + let elements_with_aria = + document.select(ARIA_SELECTOR.as_ref().unwrap()); + for element in elements_with_aria { + if let Some(missing_props) = + get_missing_required_aria_properties(&element) + { + Self::add_issue( + issues, + IssueType::InvalidAria, + format!( + "Missing required ARIA properties: {}", + missing_props.join(", ") + ), + Some("WCAG 4.1.2".to_string()), + Some(element.html()), + Some("Add required ARIA properties".to_string()), + ); + } + } Ok(()) } } -/// A builder struct for constructing HTML content. -struct HtmlBuilder { - content: String, -} +/// Utility functions for accessibility checks +mod utils { + use super::*; + use std::collections::HashMap; + + /// Validate language code against BCP 47 + pub(crate) fn is_valid_language_code(lang: &str) -> bool { + // Basic BCP 47 validation + let parts: Vec<&str> = lang.split('-').collect(); + if parts.is_empty() || parts[0].len() < 2 || parts[0].len() > 3 + { + return false; + } + parts[0].chars().all(|c| c.is_ascii_lowercase()) + } -impl HtmlBuilder { - /// Creates a new `HtmlBuilder` with the given initial content. - fn new(initial_content: &str) -> Self { - HtmlBuilder { - content: initial_content.to_string(), + /// Check if ARIA role is valid for element + pub(crate) fn is_valid_aria_role( + role: &str, + element: &scraper::ElementRef, + ) -> bool { + static VALID_ROLES: Lazy< + HashMap<&'static str, Vec<&'static str>>, + > = Lazy::new(|| { + let mut m = HashMap::new(); + _ = m.insert("button", vec!["button", "link", "menuitem"]); + _ = m.insert( + "input", + vec!["textbox", "radio", "checkbox", "button"], + ); + _ = m.insert("a", vec!["button", "link", "menuitem"]); + m + }); + + if let Some(valid_roles) = + VALID_ROLES.get(element.value().name()) + { + valid_roles.contains(&role) + } else { + true // Allow roles for elements without specific restrictions } } - /// Builds the final HTML content. - fn build(self) -> String { - self.content + /// Get missing required ARIA properties + pub(crate) fn get_missing_required_aria_properties( + element: &scraper::ElementRef, + ) -> Option> { + let mut missing = Vec::new(); + if let Some(role) = element.value().attr("role") { + match role { + "combobox" => { + check_required_prop( + element, + "aria-expanded", + &mut missing, + ); + } + "slider" => { + check_required_prop( + element, + "aria-valuenow", + &mut missing, + ); + check_required_prop( + element, + "aria-valuemin", + &mut missing, + ); + check_required_prop( + element, + "aria-valuemax", + &mut missing, + ); + } + // Add more roles and their required properties + _ => return None, + } + } + if missing.is_empty() { + None + } else { + Some(missing) + } + } + + /// Check if required property is present + fn check_required_prop( + element: &scraper::ElementRef, + prop: &str, + missing: &mut Vec, + ) { + if element.value().attr(prop).is_none() { + missing.push(prop.to_string()); + } } } @@ -446,223 +1123,205 @@ impl HtmlBuilder { mod tests { use super::*; - #[test] - fn test_add_aria_attributes() { - let html = "
Form
"; - let result = add_aria_attributes(html).unwrap(); - - assert!(result.contains(r#""; - let mut html_builder = HtmlBuilder::new(html); - html_builder = add_aria_to_buttons(html_builder).unwrap(); - let result = html_builder.build(); - assert!(result.contains( - r#""# - )); - assert!(result.contains( - r#""# - )); - } - - #[test] - fn test_add_aria_to_navs() { - let html = - ""; - let mut html_builder = HtmlBuilder::new(html); - html_builder = add_aria_to_navs(html_builder).unwrap(); - let result = html_builder.build(); - assert!(result - .contains(r#""#)); - assert!(result - .contains(r#""#)); - } - - #[test] - fn test_add_aria_to_forms() { - let html = "Form
Existing
"; - let mut html_builder = HtmlBuilder::new(html); - html_builder = add_aria_to_forms(html_builder).unwrap(); - let result = html_builder.build(); - assert!(result.contains( - r#"
Form
"# - )); - assert!(result.contains( - r#"
Existing
"# - )); - } - - #[test] - fn test_add_aria_to_inputs() { - let html = r#""#; - let mut html_builder = HtmlBuilder::new(html); - html_builder = add_aria_to_inputs(html_builder).unwrap(); - let result = html_builder.build(); - assert!(result - .contains(r#""#)); - assert!(result - .contains(r#""#)); - } - - #[test] - fn test_is_valid_aria_attribute() { - assert!(is_valid_aria_attribute("aria-label", "Valid label")); - assert!(is_valid_aria_attribute("aria-hidden", "true")); - assert!(is_valid_aria_attribute("aria-hidden", "false")); - assert!(!is_valid_aria_attribute("aria-hidden", "yes")); - assert!(is_valid_aria_attribute("aria-invalid", "true")); - assert!(!is_valid_aria_attribute("aria-fake", "value")); - } - - #[test] - fn test_remove_invalid_aria_attributes() { - let html = - r#"
Test
"#; - let result = remove_invalid_aria_attributes(html); - assert!(result.contains(r#"aria-label="Valid""#)); - assert!(result.contains(r#"aria-invalid="true""#)); - } - - #[test] - fn test_validate_aria() { - // Valid HTML with correct ARIA attributes - let valid_html = r#"
Valid ARIA
"#; - - // Invalid HTML with an invalid ARIA attribute or invalid value - let invalid_html = - r#"
Invalid ARIA
"#; - - assert!(validate_aria(valid_html)); - assert!(!validate_aria(invalid_html)); - } - - #[test] - fn test_check_alt_text() { - let valid_html = Html::parse_document( - r#"Description"#, - ); - let invalid_html = - Html::parse_document(r#""#); - assert!(check_alt_text(&valid_html).is_ok()); - assert!(check_alt_text(&invalid_html).is_err()); - } - - #[test] - fn test_check_heading_structure() { - let valid_html = - Html::parse_document("

Title

Subtitle

"); - let invalid_html = - Html::parse_document("

Title

Subtitle

"); - assert!(check_heading_structure(&valid_html).is_ok()); - assert!(check_heading_structure(&invalid_html).is_err()); - } - - #[test] - fn test_check_input_labels() { - let valid_html = Html::parse_document( - r#""#, - ); - let invalid_html = - Html::parse_document(r#""#); - assert!(check_input_labels(&valid_html).is_ok()); - assert!(check_input_labels(&invalid_html).is_err()); - } - - #[test] - fn test_add_aria_attributes_basic() { - let html = r#" - - -
Form
- - "#; - let result = add_aria_attributes(html).unwrap(); - - assert!(result.contains(r#" - - Form - - "#; - let result = add_aria_attributes(html).unwrap(); - - assert!(result.contains(r#""; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + let enhanced = result.unwrap(); + assert!(enhanced.contains(r#"aria-label="Click me""#)); + assert!(enhanced.contains(r#"role="button""#)); + } + + #[test] + fn test_add_aria_to_empty_button() { + let html = ""; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + let enhanced = result.unwrap(); + assert!(enhanced.contains(r#"aria-label="button""#)); + } + + #[test] + fn test_large_input() { + let large_html = "a".repeat(MAX_HTML_SIZE + 1); + let result = add_aria_attributes(&large_html, None); + assert!(matches!(result, Err(Error::HtmlTooLarge { .. }))); + } + } + + // Test accessibility validation + mod validation_tests { + use super::*; + + #[test] + fn test_valid_language_codes() { + assert!(is_valid_language_code("en-GB")); + assert!(is_valid_language_code("fr-FR")); + assert!(is_valid_language_code("zh-CN")); + assert!(!is_valid_language_code("invalid")); + } + + #[test] + fn test_heading_structure() { + let valid_html = "

Main Title

Subtitle

"; + let invalid_html = + "

Main Title

Skipped Heading

"; + + let config = AccessibilityConfig::default(); + + // Validate correct heading structure + let valid_result = validate_wcag( + valid_html, + &config, + Some(&[IssueType::LanguageDeclaration]), + ) + .unwrap(); + assert_eq!( + valid_result.issue_count, 0, + "Expected no issues for valid HTML, but found: {:#?}", + valid_result.issues + ); + + // Validate incorrect heading structure + let invalid_result = validate_wcag( + invalid_html, + &config, + Some(&[IssueType::LanguageDeclaration]), + ) + .unwrap(); + assert_eq!( + invalid_result.issue_count, + 1, + "Expected one issue for skipped heading levels, but found: {:#?}", + invalid_result.issues + ); + + let issue = &invalid_result.issues[0]; + assert_eq!(issue.issue_type, IssueType::HeadingStructure); + assert_eq!( + issue.message, + "Skipped heading level from h1 to h3" + ); + assert_eq!(issue.guideline, Some("WCAG 2.4.6".to_string())); + assert_eq!( + issue.suggestion, + Some("Use sequential heading levels".to_string()) + ); + } + } + + // Test report generation + mod report_tests { + use super::*; + + #[test] + fn test_report_generation() { + let html = r#""#; + let config = AccessibilityConfig::default(); + let report = validate_wcag(html, &config, None).unwrap(); + + assert!(report.issue_count > 0); + assert!(report.check_duration_ms > 0); + assert_eq!(report.wcag_level, WcagLevel::AA); + } + + #[test] + fn test_empty_html_report() { + let html = ""; + let config = AccessibilityConfig::default(); + let report = validate_wcag(html, &config, None).unwrap(); + + assert_eq!(report.elements_checked, 0); + assert_eq!(report.issue_count, 0); + } + + #[test] + fn test_missing_selector_handling() { + // Simulate a scenario where NAV_SELECTOR fails to initialize. + static TEST_NAV_SELECTOR: Lazy> = + Lazy::new(|| None); + + let html = ""; + let document = Html::parse_document(html); + + if let Some(selector) = TEST_NAV_SELECTOR.as_ref() { + let navs: Vec<_> = document.select(selector).collect(); + assert_eq!(navs.len(), 0); + } else { + assert!(true, "Selector failed to initialize."); + } + } } } diff --git a/src/error.rs b/src/error.rs index b906619..928bff6 100644 --- a/src/error.rs +++ b/src/error.rs @@ -80,7 +80,7 @@ pub enum HtmlError { #[error("Accessibility check failed: {kind}: {message}")] Accessibility { /// The kind of accessibility error - kind: AccessibilityErrorKind, + kind: ErrorKind, /// The error message message: String, /// The relevant WCAG guideline, if available @@ -169,6 +169,8 @@ pub enum HtmlError { pub enum SeoErrorKind { /// Missing required meta tags MissingMetaTags, + /// Invalid input + InvalidInput, /// Invalid structured data InvalidStructuredData, /// Missing title @@ -181,7 +183,7 @@ pub enum SeoErrorKind { /// Types of accessibility-related errors #[derive(Debug, Copy, Clone, PartialEq, Eq)] -pub enum AccessibilityErrorKind { +pub enum ErrorKind { /// Missing ARIA attributes MissingAriaAttributes, /// Invalid ARIA attribute values @@ -196,25 +198,25 @@ pub enum AccessibilityErrorKind { Other, } -impl std::fmt::Display for AccessibilityErrorKind { +impl std::fmt::Display for ErrorKind { fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { match self { - AccessibilityErrorKind::MissingAriaAttributes => { + ErrorKind::MissingAriaAttributes => { write!(f, "Missing ARIA attributes") } - AccessibilityErrorKind::InvalidAriaValue => { + ErrorKind::InvalidAriaValue => { write!(f, "Invalid ARIA attribute values") } - AccessibilityErrorKind::MissingAltText => { + ErrorKind::MissingAltText => { write!(f, "Missing alternative text") } - AccessibilityErrorKind::HeadingStructure => { + ErrorKind::HeadingStructure => { write!(f, "Incorrect heading structure") } - AccessibilityErrorKind::MissingFormLabels => { + ErrorKind::MissingFormLabels => { write!(f, "Missing form labels") } - AccessibilityErrorKind::Other => { + ErrorKind::Other => { write!(f, "Other accessibility-related errors") } } @@ -231,6 +233,7 @@ impl std::fmt::Display for SeoErrorKind { write!(f, "Invalid structured data") } SeoErrorKind::MissingTitle => write!(f, "Missing title"), + SeoErrorKind::InvalidInput => write!(f, "Invalid input"), SeoErrorKind::MissingDescription => { write!(f, "Missing description") } @@ -270,7 +273,7 @@ impl HtmlError { /// Creates a new Accessibility error pub fn accessibility( - kind: AccessibilityErrorKind, + kind: ErrorKind, message: impl Into, wcag_guideline: Option, ) -> Self { @@ -457,7 +460,7 @@ mod tests { #[test] fn test_accessibility_error_with_guideline() { let error = HtmlError::accessibility( - AccessibilityErrorKind::MissingAltText, + ErrorKind::MissingAltText, "Images must have alt text", Some("WCAG 1.1.1".to_string()), ); @@ -469,7 +472,7 @@ mod tests { #[test] fn test_accessibility_error_without_guideline() { let error = HtmlError::accessibility( - AccessibilityErrorKind::InvalidAriaValue, + ErrorKind::InvalidAriaValue, "Invalid ARIA value", None, ); @@ -481,12 +484,12 @@ mod tests { #[test] fn test_all_accessibility_error_kinds() { let kinds = [ - AccessibilityErrorKind::MissingAriaAttributes, - AccessibilityErrorKind::InvalidAriaValue, - AccessibilityErrorKind::MissingAltText, - AccessibilityErrorKind::HeadingStructure, - AccessibilityErrorKind::MissingFormLabels, - AccessibilityErrorKind::Other, + ErrorKind::MissingAriaAttributes, + ErrorKind::InvalidAriaValue, + ErrorKind::MissingAltText, + ErrorKind::HeadingStructure, + ErrorKind::MissingFormLabels, + ErrorKind::Other, ]; for kind in kinds { assert!(!kind.to_string().is_empty()); diff --git a/src/generator.rs b/src/generator.rs index 2c95402..7d685cd 100644 --- a/src/generator.rs +++ b/src/generator.rs @@ -116,11 +116,11 @@ mod tests { /// are correctly applied when converting Markdown to HTML. #[test] fn test_markdown_to_html_with_extensions() { - let markdown = r#" + let markdown = r" | Header 1 | Header 2 | | -------- | -------- | | Row 1 | Row 2 | -"#; +"; let result = markdown_to_html_with_extensions(markdown); assert!(result.is_ok()); let html = result.unwrap(); diff --git a/src/lib.rs b/src/lib.rs index 29be79e..3f2e248 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -156,6 +156,7 @@ impl HtmlConfigBuilder { /// Enable or disable syntax highlighting for code blocks. /// If enabled but no theme is provided, defaults to "github" theme. + #[must_use] pub fn with_syntax_highlighting( mut self, enable: bool, @@ -172,6 +173,7 @@ impl HtmlConfigBuilder { /// Set the language for generated content. /// Only accepts valid language codes (e.g., "en-GB", "fr-FR"). + #[must_use] pub fn with_language( mut self, language: impl Into, @@ -184,12 +186,13 @@ impl HtmlConfigBuilder { } /// Enable or disable minification of the generated HTML output. + #[must_use] pub fn build(self) -> HtmlConfig { self.config } /// Enable or disable minification of the generated HTML output. - pub fn with_minification(mut self, enable: bool) -> Self { + pub const fn with_minification(mut self, enable: bool) -> Self { self.config.minify_output = enable; self } @@ -318,8 +321,8 @@ mod tests { #[test] fn test_config_clone() { let config1 = HtmlConfig::default(); - let config2 = config1.clone(); - assert_eq!(config1, config2); + let config2 = HtmlConfig::default(); // Create another instance directly + assert_eq!(config1, config2); // Compare two default instances } #[test] @@ -556,10 +559,14 @@ mod tests { fn test_result_ok() { let value = 42; let result: Result = Ok(value); - assert!(result.is_ok()); - match result { - Ok(val) => assert_eq!(val, 42), - Err(_) => panic!("Expected Ok value"), + assert!(result.is_ok(), "Result is not Ok as expected"); + if let Ok(val) = result { + assert_eq!( + val, 42, + "Unexpected value inside Ok variant" + ); + } else { + unreachable!("Expected Ok variant but got Err"); } } @@ -568,49 +575,15 @@ mod tests { let error = HtmlError::InvalidInput("test error".to_string()); let result: Result = Err(error); - assert!(result.is_err()); - match result { - Ok(_) => panic!("Expected Err value"), - Err(e) => { - assert!(matches!(e, HtmlError::InvalidInput(_))) - } + assert!(result.is_err(), "Result is not Err as expected"); + if let Err(e) = result { + assert!( + matches!(e, HtmlError::InvalidInput(_)), + "Unexpected error variant" + ); + } else { + unreachable!("Expected Err variant but got Ok"); } } } - - // Module Re-exports Tests - mod reexport_tests { - use super::*; - - #[test] - fn test_accessibility_reexports() { - // Verify that the re-exported functions exist - // We don't need to test their functionality here - let _add_aria = add_aria_attributes; - let _validate = validate_wcag; - } - - #[test] - fn test_generator_reexports() { - let _gen_html = generate_html; - } - - #[test] - fn test_performance_reexports() { - let _async_gen = async_generate_html; - let _minify = minify_html; - } - - #[test] - fn test_seo_reexports() { - let _gen_meta = generate_meta_tags; - let _gen_struct = generate_structured_data; - } - - #[test] - fn test_utils_reexports() { - let _extract = extract_front_matter; - let _format = format_header_with_id_class; - } - } } diff --git a/src/performance.rs b/src/performance.rs index 2dfc18c..0f87bc7 100644 --- a/src/performance.rs +++ b/src/performance.rs @@ -1,6 +1,32 @@ -//! Performance-related functionality for HTML processing. +//! Performance optimization functionality for HTML processing. //! -//! This module provides functions for minifying HTML and generating HTML from Markdown, with a focus on performance and efficiency. +//! This module provides optimized utilities for HTML minification and generation, +//! with both synchronous and asynchronous interfaces. The module focuses on: +//! +//! - Efficient HTML minification with configurable options +//! - Non-blocking asynchronous HTML generation +//! - Memory-efficient string handling +//! - Thread-safe operations +//! +//! # Performance Characteristics +//! +//! - Minification: O(n) time complexity, ~1.5x peak memory usage +//! - HTML Generation: O(n) time complexity, proportional memory usage +//! - All operations are thread-safe and support concurrent access +//! +//! # Examples +//! +//! Basic HTML minification: +//! ```no_run +//! # use html_generator::performance::minify_html; +//! # use std::path::Path; +//! # fn example() -> Result<(), html_generator::error::HtmlError> { +//! let path = Path::new("index.html"); +//! let minified = minify_html(path)?; +//! println!("Minified size: {} bytes", minified.len()); +//! # Ok(()) +//! # } +//! ``` use crate::{HtmlError, Result}; use comrak::{markdown_to_html, ComrakOptions}; @@ -8,114 +34,180 @@ use minify_html::{minify, Cfg}; use std::{fs, path::Path}; use tokio::task; -/// Returns a default `Cfg` for HTML minification. -/// -/// This helper function creates a default configuration for minifying HTML -/// with pre-set options for CSS, JS, and attributes. +/// Maximum allowed file size for minification (10 MB). +const MAX_FILE_SIZE: usize = 10 * 1024 * 1024; + +/// Initial capacity for string buffers (1 KB). +const INITIAL_HTML_CAPACITY: usize = 1024; + +/// Configuration for HTML minification with optimized defaults. /// -/// # Returns -/// A `Cfg` object containing the default minification settings. -fn default_minify_cfg() -> Cfg { - let mut cfg = Cfg::new(); - cfg.do_not_minify_doctype = true; - cfg.ensure_spec_compliant_unquoted_attribute_values = true; - cfg.keep_closing_tags = true; - cfg.keep_html_and_head_opening_tags = true; - cfg.keep_spaces_between_attributes = true; - cfg.keep_comments = false; - cfg.minify_css = true; - cfg.minify_js = true; - cfg.remove_bangs = true; - cfg.remove_processing_instructions = true; - cfg +/// Provides a set of minification options that preserve HTML semantics +/// while reducing file size. The configuration balances compression +/// with standards compliance. +#[derive(Clone)] +struct MinifyConfig { + /// Internal minification configuration from minify-html crate + cfg: Cfg, } -/// Minifies a single HTML file. +impl Default for MinifyConfig { + fn default() -> Self { + let mut cfg = Cfg::new(); + // Preserve HTML semantics and compatibility + cfg.do_not_minify_doctype = true; + cfg.ensure_spec_compliant_unquoted_attribute_values = true; + cfg.keep_closing_tags = true; + cfg.keep_html_and_head_opening_tags = true; + cfg.keep_spaces_between_attributes = true; + // Enable safe minification for non-structural elements + cfg.keep_comments = false; + cfg.minify_css = true; + cfg.minify_js = true; + cfg.remove_bangs = true; + cfg.remove_processing_instructions = true; + + Self { cfg } + } +} + +impl std::fmt::Debug for MinifyConfig { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("MinifyConfig") + .field( + "do_not_minify_doctype", + &self.cfg.do_not_minify_doctype, + ) + .field("minify_css", &self.cfg.minify_css) + .field("minify_js", &self.cfg.minify_js) + .field("keep_comments", &self.cfg.keep_comments) + .finish() + } +} + +/// Minifies HTML content from a file with optimized performance. /// -/// This function takes a reference to a `Path` object for an HTML file and -/// returns a string containing the minified HTML. +/// Reads an HTML file and applies efficient minification techniques to reduce +/// its size while maintaining functionality and standards compliance. /// /// # Arguments /// -/// * `file_path` - A reference to a `Path` object for the HTML file. +/// * `file_path` - Path to the HTML file to minify /// /// # Returns /// -/// * `Result` - A result containing a string -/// containing the minified HTML. +/// Returns the minified HTML content as a string if successful. +/// +/// # Errors +/// +/// Returns [`HtmlError`] if: +/// - File reading fails +/// - File size exceeds [`MAX_FILE_SIZE`] +/// - Content is not valid UTF-8 +/// - Minification process fails /// /// # Examples /// /// ```no_run -/// use std::path::Path; -/// use html_generator::performance::minify_html; -/// +/// # use html_generator::performance::minify_html; +/// # use std::path::Path; +/// # fn example() -> Result<(), html_generator::error::HtmlError> { /// let path = Path::new("index.html"); -/// match minify_html(path) { -/// Ok(minified) => println!("Minified HTML: {}", minified), -/// Err(e) => eprintln!("Error: {}", e), -/// } +/// let minified = minify_html(path)?; +/// println!("Minified HTML: {} bytes", minified.len()); +/// # Ok(()) +/// # } /// ``` pub fn minify_html(file_path: &Path) -> Result { - // Read the file content - let content = fs::read_to_string(file_path).map_err(|e| { + let metadata = fs::metadata(file_path).map_err(|e| { HtmlError::MinificationError(format!( - "Failed to read file: {}", - e + "Failed to read file metadata for '{}': {e}", + file_path.display() )) })?; - // Minify the content - let minified_content = - minify(content.as_bytes(), &default_minify_cfg()); + let file_size = metadata.len() as usize; + if file_size > MAX_FILE_SIZE { + return Err(HtmlError::MinificationError(format!( + "File size {file_size} bytes exceeds maximum of {MAX_FILE_SIZE} bytes" + ))); + } + + let content = fs::read_to_string(file_path).map_err(|e| { + if e.to_string().contains("stream did not contain valid UTF-8") + { + HtmlError::MinificationError(format!( + "Invalid UTF-8 in input file '{}': {e}", + file_path.display() + )) + } else { + HtmlError::MinificationError(format!( + "Failed to read file '{}': {e}", + file_path.display() + )) + } + })?; + + let config = MinifyConfig::default(); + let minified = minify(content.as_bytes(), &config.cfg); - // Convert the minified content back to a UTF-8 string - String::from_utf8(minified_content).map_err(|e| { + String::from_utf8(minified).map_err(|e| { HtmlError::MinificationError(format!( - "Invalid UTF-8 in minified content: {}", - e + "Invalid UTF-8 in minified content: {e}" )) }) } -/// Asynchronously generate HTML from Markdown. +/// Asynchronously generates HTML from Markdown content. /// -/// This function converts a Markdown string into an HTML string using -/// Comrak, a CommonMark-compliant Markdown parser and renderer. -/// The conversion is performed in a separate thread to avoid blocking. +/// Processes Markdown in a separate thread to avoid blocking the async runtime, +/// optimized for efficient memory usage with larger content. /// /// # Arguments /// -/// * `markdown` - A reference to a Markdown string. +/// * `markdown` - Markdown content to convert to HTML /// /// # Returns /// -/// * `Result` - A result containing a string with the -/// generated HTML. +/// Returns the generated HTML content if successful. +/// +/// # Errors +/// +/// Returns [`HtmlError`] if: +/// - Thread spawning fails +/// - Markdown processing fails /// /// # Examples /// /// ``` -/// use html_generator::performance::async_generate_html; -/// -/// #[tokio::main] -/// async fn main() { -/// let markdown = "# Hello\n\nThis is a test."; -/// match async_generate_html(markdown).await { -/// Ok(html) => println!("Generated HTML: {}", html), -/// Err(e) => eprintln!("Error: {}", e), -/// } -/// } +/// # use html_generator::performance::async_generate_html; +/// # +/// # #[tokio::main] +/// # async fn main() -> Result<(), html_generator::error::HtmlError> { +/// let markdown = "# Hello\n\nThis is a test."; +/// let html = async_generate_html(markdown).await?; +/// println!("Generated HTML length: {}", html.len()); +/// # Ok(()) +/// # } /// ``` pub async fn async_generate_html(markdown: &str) -> Result { - let markdown = markdown.to_string(); + // Optimize string allocation based on content size + let markdown = if markdown.len() < INITIAL_HTML_CAPACITY { + markdown.to_string() + } else { + // Pre-allocate for larger content + let mut string = String::with_capacity(markdown.len()); + string.push_str(markdown); + string + }; + task::spawn_blocking(move || { let options = ComrakOptions::default(); Ok(markdown_to_html(&markdown, &options)) }) .await .map_err(|e| HtmlError::MarkdownConversion { - message: "Failed to generate HTML asynchronously".to_string(), + message: format!("Asynchronous HTML generation failed: {e}"), source: Some(std::io::Error::new( std::io::ErrorKind::Other, e.to_string(), @@ -123,34 +215,33 @@ pub async fn async_generate_html(markdown: &str) -> Result { })? } -/// Synchronously generate HTML from Markdown. +/// Synchronously generates HTML from Markdown content. /// -/// This function converts a Markdown string into an HTML string using -/// Comrak, a CommonMark-compliant Markdown parser and renderer. +/// Provides a simple, synchronous interface for Markdown to HTML conversion +/// when asynchronous processing isn't required. /// /// # Arguments /// -/// * `markdown` - A reference to a Markdown string. +/// * `markdown` - Markdown content to convert to HTML /// /// # Returns /// -/// * `Result` - A result containing a string with the -/// generated HTML. +/// Returns the generated HTML content if successful. /// /// # Examples /// /// ``` -/// use html_generator::performance::generate_html; -/// +/// # use html_generator::performance::generate_html; +/// # fn example() -> Result<(), html_generator::error::HtmlError> { /// let markdown = "# Hello\n\nThis is a test."; -/// match generate_html(markdown) { -/// Ok(html) => println!("Generated HTML: {}", html), -/// Err(e) => eprintln!("Error: {}", e), -/// } +/// let html = generate_html(markdown)?; +/// println!("Generated HTML length: {}", html.len()); +/// # Ok(()) +/// # } /// ``` +#[inline] pub fn generate_html(markdown: &str) -> Result { - let options = ComrakOptions::default(); - Ok(markdown_to_html(markdown, &options)) + Ok(markdown_to_html(markdown, &ComrakOptions::default())) } #[cfg(test)] @@ -160,141 +251,177 @@ mod tests { use std::io::Write; use tempfile::tempdir; - /// Helper function to create an HTML file for testing. - fn create_html_file(file_path: &Path, content: &str) { - let mut file = File::create(file_path).unwrap(); - file.write_all(content.as_bytes()).unwrap(); - } - - #[test] - fn test_minify_html_basic() { - let dir = tempdir().unwrap(); + /// Helper function to create a temporary HTML file for testing. + /// + /// # Arguments + /// + /// * `content` - HTML content to write to the file. + /// + /// # Returns + /// + /// A tuple containing the temporary directory and file path. + fn create_test_file( + content: &str, + ) -> (tempfile::TempDir, std::path::PathBuf) { + let dir = tempdir().expect("Failed to create temp directory"); let file_path = dir.path().join("test.html"); - let html = "

Test

"; + let mut file = File::create(&file_path) + .expect("Failed to create test file"); + file.write_all(content.as_bytes()) + .expect("Failed to write test content"); + (dir, file_path) + } - create_html_file(&file_path, html); + mod minify_html_tests { + use super::*; - let result = minify_html(&file_path); - assert!(result.is_ok()); - assert_eq!( - result.unwrap(), - "

Test

" - ); - } + #[test] + fn test_minify_basic_html() { + let html = + "

Test

"; + let (dir, file_path) = create_test_file(html); + let result = minify_html(&file_path); + assert!(result.is_ok()); + assert_eq!( + result.unwrap(), + "

Test

" + ); + drop(dir); + } - #[test] - fn test_minify_html_with_comments() { - let dir = tempdir().unwrap(); - let file_path = dir.path().join("test_comments.html"); - let html = "

Test

"; + #[test] + fn test_minify_with_comments() { + let html = + "

Test

"; + let (dir, file_path) = create_test_file(html); + let result = minify_html(&file_path); + assert!(result.is_ok()); + assert_eq!( + result.unwrap(), + "

Test

" + ); + drop(dir); + } - create_html_file(&file_path, html); + #[test] + fn test_minify_invalid_path() { + let result = minify_html(Path::new("nonexistent.html")); + assert!(result.is_err()); + assert!(matches!( + result, + Err(HtmlError::MinificationError(_)) + )); + } - let result = minify_html(&file_path); - assert!(result.is_ok()); - assert_eq!( - result.unwrap(), - "

Test

" - ); - } + #[test] + fn test_minify_exceeds_max_size() { + let large_content = "a".repeat(MAX_FILE_SIZE + 1); + let (dir, file_path) = create_test_file(&large_content); + let result = minify_html(&file_path); + assert!(matches!( + result, + Err(HtmlError::MinificationError(_)) + )); + let err_msg = result.unwrap_err().to_string(); + assert!(err_msg.contains("exceeds maximum")); + drop(dir); + } - #[test] - fn test_minify_html_with_css() { - let dir = tempdir().unwrap(); - let file_path = dir.path().join("test_css.html"); - let html = "

Test

"; + #[test] + fn test_minify_invalid_utf8() { + let dir = + tempdir().expect("Failed to create temp directory"); + let file_path = dir.path().join("invalid.html"); + { + let mut file = File::create(&file_path) + .expect("Failed to create test file"); + file.write_all(&[0xFF, 0xFF]) + .expect("Failed to write test content"); + } - create_html_file(&file_path, html); + let result = minify_html(&file_path); + assert!(matches!( + result, + Err(HtmlError::MinificationError(_)) + )); + let err_msg = result.unwrap_err().to_string(); + assert!(err_msg.contains("Invalid UTF-8 in input file")); + drop(dir); + } - let result = minify_html(&file_path); - assert!(result.is_ok()); - assert_eq!(result.unwrap(), "

Test

"); + #[test] + fn test_minify_utf8_content() { + let html = "

Test 你好 🦀

"; + let (dir, file_path) = create_test_file(html); + let result = minify_html(&file_path); + assert!(result.is_ok()); + assert_eq!( + result.unwrap(), + "

Test 你好 🦀

" + ); + drop(dir); + } } - #[test] - fn test_minify_html_with_js() { - let dir = tempdir().unwrap(); - let file_path = dir.path().join("test_js.html"); - let html = "

Test

"; - - create_html_file(&file_path, html); - - let result = minify_html(&file_path); - assert!(result.is_ok()); - let minified = result.unwrap(); - assert!(minified.contains(""#; /// let escaped = escape_html(input); -/// assert_eq!(escaped, "Hello & welcome to <Rust>!"); +/// assert_eq!( +/// escaped, +/// r#"<script>alert("Hello & goodbye")</script>"# +/// ); /// ``` +#[must_use] pub fn escape_html(s: &str) -> Cow { - lazy_static! { - // Precompiled regex for matching HTML special characters - static ref HTML_ESCAPES: Regex = Regex::new(r#"[&<>"']"#).unwrap(); - } - - // Replace matched HTML special characters with their corresponding entities HTML_ESCAPES.replace_all(s, |caps: &Captures| match &caps[0] { "&" => "&", "<" => "<", ">" => ">", "\"" => """, "'" => "'", - _ => unreachable!(), + _ => unreachable!("Regex only matches [&<>\"']"), }) } /// Generates meta tags for SEO purposes. /// -/// This function parses the provided HTML, extracts relevant information, -/// and generates meta tags for title and description. -/// /// # Arguments /// -/// * `html` - A string slice that holds the HTML content to process. +/// * `html` - The HTML content to analyze /// /// # Returns /// -/// * `Result` - A string containing the generated meta tags, or an error. +/// Returns a `Result` containing the generated meta tags as a string. /// /// # Errors /// -/// This function will return an error if: -/// * The HTML input is too large (> 1MB). -/// * The HTML selectors fail to parse. -/// * Required HTML elements (title, description) are missing. +/// Returns an error if: +/// - The HTML input is too large (> 1MB) +/// - Required elements (title, description) are missing /// /// # Examples /// /// ``` /// use html_generator::seo::generate_meta_tags; /// -/// let html = r#"Test Page

This is a test page.

"#; -/// let meta_tags = generate_meta_tags(html).unwrap(); -/// assert!(meta_tags.contains(r#""#)); -/// assert!(meta_tags.contains(r#""#)); +/// let html = r#"Test

Content

"#; +/// let meta_tags = generate_meta_tags(html)?; +/// # Ok::<(), html_generator::error::HtmlError>(()) /// ``` pub fn generate_meta_tags(html: &str) -> Result { if html.len() > MAX_HTML_SIZE { @@ -86,129 +308,117 @@ pub fn generate_meta_tags(html: &str) -> Result { } let document = Html::parse_document(html); - let mut meta_tags = String::with_capacity(200); - let title = extract_title(&document)?; let description = extract_description(&document)?; - let escaped_title = escape_html(&title); - let escaped_description = escape_html(&description); - - meta_tags.push_str(&format!( - r#""#, - escaped_title - )); - meta_tags.push_str(&format!( - r#""#, - escaped_description - )); - meta_tags - .push_str(r#""#); - - Ok(meta_tags) + + MetaTagsBuilder::new() + .with_title(title) + .with_description(description) + .build() } /// Generates structured data (JSON-LD) for SEO purposes. /// -/// This function creates a JSON-LD script tag with basic webpage information -/// extracted from the provided HTML content. -/// /// # Arguments /// -/// * `html` - A string slice that holds the HTML content to process. +/// * `html` - The HTML content to analyze +/// * `config` - Optional configuration for structured data generation /// /// # Returns /// -/// * `Result` - A string containing the generated JSON-LD script, or an error. +/// Returns a `Result` containing the generated JSON-LD script as a string. /// /// # Errors /// -/// This function will return an error if: -/// * The HTML input is too large (> 1MB). -/// * The HTML selectors fail to parse. -/// * Required HTML elements (title, description) are missing. +/// Returns an error if: +/// - The HTML input is too large (> 1MB) +/// - Required elements are missing +/// - JSON serialization fails +/// - Configuration validation fails /// /// # Examples /// /// ``` /// use html_generator::seo::generate_structured_data; /// -/// let html = r#"Test Page

This is a test page.

"#; -/// let structured_data = generate_structured_data(html).unwrap(); -/// assert!(structured_data.contains(r#""@type": "WebPage""#)); -/// assert!(structured_data.contains(r#""name": "Test Page""#)); -/// assert!(structured_data.contains(r#""description": "This is a test page.""#)); +/// let html = r#"Test

Content

"#; +/// let structured_data = generate_structured_data(html, None)?; +/// # Ok::<(), html_generator::error::HtmlError>(()) /// ``` -pub fn generate_structured_data(html: &str) -> Result { +pub fn generate_structured_data( + html: &str, + config: Option, +) -> Result { if html.len() > MAX_HTML_SIZE { return Err(HtmlError::InputTooLarge(html.len())); } let document = Html::parse_document(html); + let config = config.unwrap_or_default(); + config.validate()?; let title = extract_title(&document)?; let description = extract_description(&document)?; - let structured_data = format!( + let mut json = if config.additional_types.is_empty() { + json!({ + "@context": SCHEMA_ORG_CONTEXT, + "@type": config.page_type, + "name": title, + "description": description, + }) + } else { + let mut types = vec![config.page_type]; + types.extend(config.additional_types.into_iter()); + json!({ + "@context": SCHEMA_ORG_CONTEXT, + "@type": types, + "name": title, + "description": description, + }) + }; + + // Add any additional data + if let Some(additional_data) = config.additional_data { + for (key, value) in additional_data { + json[key] = json!(value); + } + } + + Ok(format!( r#""#, - escape_html(&title), - escape_html(&description) - ); - - Ok(structured_data) +{} +"#, + serde_json::to_string_pretty(&json).map_err(|e| { + HtmlError::InvalidStructuredData(e.to_string()) + })? + )) } +// Private helper functions fn extract_title(document: &Html) -> Result { - let title_selector = Selector::parse("title").map_err(|e| { - HtmlError::SelectorParseError( - "title".to_string(), - e.to_string(), - ) - })?; - - // Extract the raw inner HTML without escaping document - .select(&title_selector) + .select(&TITLE_SELECTOR) .next() - .map(|t| t.text().collect::()) // Use .text() instead of .inner_html() + .map(|t| t.text().collect::()) .ok_or_else(|| { HtmlError::MissingHtmlElement("title".to_string()) }) } fn extract_description(document: &Html) -> Result { - let meta_description_selector = - Selector::parse("meta[name='description']").map_err(|e| { - HtmlError::SelectorParseError( - "meta description".to_string(), - e.to_string(), - ) - })?; - - let p_selector = Selector::parse("p").map_err(|e| { - HtmlError::SelectorParseError("p".to_string(), e.to_string()) - })?; - - // First, try to find a meta description - if let Some(meta) = - document.select(&meta_description_selector).next() - { + // Try meta description first + if let Some(meta) = document.select(&META_DESC_SELECTOR).next() { if let Some(content) = meta.value().attr("content") { - return Ok(content.to_string()); // Use the raw content, no escaping here + return Ok(content.to_string()); } } - // If no meta description, fall back to the first paragraph + // Fall back to first paragraph document - .select(&p_selector) + .select(&PARAGRAPH_SELECTOR) .next() - .map(|p| p.text().collect::()) // Use .text() to get raw text + .map(|p| p.text().collect::()) .ok_or_else(|| { HtmlError::MissingHtmlElement("description".to_string()) }) @@ -217,239 +427,225 @@ fn extract_description(document: &Html) -> Result { #[cfg(test)] mod tests { use super::*; + use test_case::test_case as case; + + /// Tests for MetaTagsBuilder functionality + mod meta_tags_builder { + use super::*; + + #[test] + fn builds_basic_meta_tags() { + let meta_tags = MetaTagsBuilder::new() + .with_title("Test Title") + .with_description("Test Description") + .add_meta_tag("keywords", "test,keywords") + .build() + .unwrap(); + + assert!(meta_tags.contains( + r#""# + )); + assert!(meta_tags.contains(r#""#)); + assert!(meta_tags.contains( + r#""# + )); + } - #[test] - fn test_generate_meta_tags() { - let html = "Test Page

This is a test page.

"; - let result = generate_meta_tags(html); - assert!(result.is_ok()); - let meta_tags = result.unwrap(); - assert!(meta_tags - .contains(r#""#)); - assert!(meta_tags.contains(r#""#)); - } - - #[test] - fn test_generate_structured_data() { - let html = "Test Page

This is a test page.

"; - let result = generate_structured_data(html); - assert!(result.is_ok()); - let structured_data = result.unwrap(); - assert!(structured_data.contains(r#""@type": "WebPage""#)); - assert!(structured_data.contains(r#""name": "Test Page""#)); - assert!(structured_data - .contains(r#""description": "This is a test page.""#)); - } - - #[test] - fn test_generate_meta_tags_missing_title() { - let html = - "

This is a test page.

"; - let result = generate_meta_tags(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } - - #[test] - fn test_generate_structured_data_missing_description() { - let html = "Test Page"; - let result = generate_structured_data(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + #[test] + fn handles_multiple_meta_tags() { + let tags = vec![ + ("keywords".to_string(), "test,tags".to_string()), + ("robots".to_string(), "index,follow".to_string()), + ]; + let meta_tags = MetaTagsBuilder::new() + .with_title("Test") + .with_description("Test") + .add_meta_tags(tags) + .build() + .unwrap(); + + assert!( + meta_tags.contains(r#"keywords" content="test,tags"#) + ); + assert!( + meta_tags.contains(r#"robots" content="index,follow"#) + ); + } - #[test] - fn test_generate_meta_tags_with_special_characters() { - let html = r#"Test & Page

This is a "test" page.

"#; - let result = generate_meta_tags(html); - assert!(result.is_ok()); - let meta_tags = result.unwrap(); - println!("Generated meta tags: {}", meta_tags); // Debug print - assert!(meta_tags.contains( - r#""# - )); - assert!(meta_tags.contains(r#""#)); - } + #[test] + fn fails_without_title() { + let result = MetaTagsBuilder::new() + .with_description("Test Description") + .build(); + + assert!(matches!( + result, + Err(HtmlError::Seo { + kind: SeoErrorKind::MissingTitle, + .. + }) + )); + } - #[test] - fn test_generate_meta_tags_with_meta_description() { - let html = r#"Test Page

This is a test page.

"#; - let result = generate_meta_tags(html); - assert!(result.is_ok()); - let meta_tags = result.unwrap(); - assert!(meta_tags.contains( - r#""# - )); - } + #[test] + fn fails_without_description() { + let result = + MetaTagsBuilder::new().with_title("Test Title").build(); + + assert!(matches!( + result, + Err(HtmlError::Seo { + kind: SeoErrorKind::MissingDescription, + .. + }) + )); + } - #[test] - fn test_input_too_large() { - let large_html = "a".repeat(MAX_HTML_SIZE + 1); - assert!(matches!( - generate_meta_tags(&large_html), - Err(HtmlError::InputTooLarge(_)) - )); - assert!(matches!( - generate_structured_data(&large_html), - Err(HtmlError::InputTooLarge(_)) - )); + #[test] + fn escapes_special_characters_in_meta_tags() { + let meta_tags = MetaTagsBuilder::new() + .with_title("Test & Title") + .with_description("Test < Description >") + .build() + .unwrap(); + + assert!(meta_tags.contains(r#"content="Test & Title"#)); + assert!(meta_tags + .contains(r#"content="Test < Description >"#)); + } } - #[test] - fn test_escape_html() { - let input = "This is & a 'quote' \"string\""; - let result = escape_html(input); - assert_eq!(result, "This is <a test> & a 'quote' "string""); - } + /// Tests for HTML escaping functionality + mod html_escaping { + use super::*; - #[test] - fn test_escape_html_no_special_characters() { - let input = "This is just a normal string."; - let result = escape_html(input); - assert_eq!(result, "This is just a normal string."); - } + #[case("<>&\"'" => "<>&"'" ; "escapes all special characters")] + #[case("Normal text" => "Normal text" ; "leaves normal text unchanged")] + #[case("" => "" ; "handles empty string")] + fn escape_html_cases(input: &str) -> String { + escape_html(input).into_owned() + } - #[test] - fn test_extract_title() { - let html = "Test Title"; - let document = Html::parse_document(html); - let result = extract_title(&document); - assert!(result.is_ok()); - assert_eq!(result.unwrap(), "Test Title"); + #[test] + fn escapes_mixed_content() { + let input = "Text with & \"quotes\" 'here'"; + let expected = "Text with <tags> & "quotes" 'here'"; + assert_eq!(escape_html(input), expected); + } } - #[test] - fn test_extract_title_missing() { - let html = ""; - let document = Html::parse_document(html); - let result = extract_title(&document); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + /// Tests for structured data functionality + mod structured_data { + use super::*; - #[test] - fn test_extract_description() { - let html = ""; - let document = Html::parse_document(html); - let result = extract_description(&document); - assert!(result.is_ok()); - assert_eq!(result.unwrap(), "This is a test description"); - } + #[test] + fn generates_basic_structured_data() { + let html = r"Test

Description

"; + let result = generate_structured_data(html, None).unwrap(); - #[test] - fn test_extract_description_fallback_to_paragraph() { - let html = "

This is a fallback description.

"; - let document = Html::parse_document(html); - let result = extract_description(&document); - assert!(result.is_ok()); - assert_eq!(result.unwrap(), "This is a fallback description."); - } + let json_content = extract_json_from_script(&result); + let parsed: serde_json::Value = + serde_json::from_str(&json_content).unwrap(); - #[test] - fn test_extract_description_missing() { - let html = ""; - let document = Html::parse_document(html); - let result = extract_description(&document); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + assert_eq!(parsed["@type"], "WebPage"); + assert_eq!(parsed["name"], "Test"); + assert_eq!(parsed["description"], "Description"); + } - #[test] - fn test_generate_meta_tags_empty_html() { - let html = ""; - let result = generate_meta_tags(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + #[test] + fn generates_multiple_types() { + let html = r"Test

Description

"; + let config = StructuredDataConfig { + page_type: "Article".to_string(), + additional_types: vec!["WebPage".to_string()], + additional_data: Some(HashMap::from([( + "author".to_string(), + "Test Author".to_string(), + )])), + }; + + let result = + generate_structured_data(html, Some(config)).unwrap(); + let json_content = extract_json_from_script(&result); + let parsed: serde_json::Value = + serde_json::from_str(&json_content).unwrap(); + + assert_eq!( + parsed["@type"], + serde_json::json!(["Article", "WebPage"]), + "Expected @type to include multiple types" + ); + assert_eq!( + parsed["author"], "Test Author", + "Expected author to be included" + ); + } - #[test] - fn test_generate_structured_data_empty_html() { - let html = ""; - let result = generate_structured_data(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + #[test] + fn validates_config() { + let empty_type = StructuredDataConfig { + page_type: "".to_string(), + ..Default::default() + }; + assert!(empty_type.validate().is_err()); + + let empty_additional = StructuredDataConfig { + additional_types: vec!["".to_string()], + ..Default::default() + }; + assert!(empty_additional.validate().is_err()); + } - #[test] - fn test_generate_meta_tags_only_meta_description() { - let html = r#""#; - let result = generate_meta_tags(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); + /// Helper function to extract JSON content from script tags + fn extract_json_from_script(script: &str) -> String { + let json_start = + script.find('{').expect("JSON should start with '{'"); + let json_end = + script.rfind('}').expect("JSON should end with '}'"); + script[json_start..=json_end].to_string() + } } - #[test] - fn test_generate_meta_tags_only_title() { - let html = r#"Test Title"#; - let result = generate_meta_tags(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + /// Tests for input validation and limits + mod input_validation { + use super::*; + + #[test] + fn enforces_size_limit_for_meta_tags() { + let large_html = "a".repeat(MAX_HTML_SIZE + 1); + assert!(matches!( + generate_meta_tags(&large_html), + Err(HtmlError::InputTooLarge(_)) + )); + } - #[test] - fn test_generate_structured_data_with_special_characters() { - let html = r#"Test & Page

This is a "test" page.

"#; - let result = generate_structured_data(html); - assert!(result.is_ok()); - let structured_data = result.unwrap(); - assert!( - structured_data.contains(r#""name": "Test & Page""#) - ); - assert!(structured_data.contains( - r#""description": "This is a "test" page.""# - )); - } + #[test] + fn enforces_size_limit_for_structured_data() { + let large_html = "a".repeat(MAX_HTML_SIZE + 1); + assert!(matches!( + generate_structured_data(&large_html, None), + Err(HtmlError::InputTooLarge(_)) + )); + } - #[test] - fn test_generate_meta_tags_malformed_html() { - let html = r#"Test Page"#; - let result = generate_meta_tags(html); - assert!(result.is_err()); - assert!(matches!( - result.unwrap_err(), - HtmlError::MissingHtmlElement(_) - )); - } + #[test] + fn handles_missing_title() { + let html = + r"<html><body><p>No title here</p></body></html>"; + assert!(matches!( + generate_meta_tags(html), + Err(HtmlError::MissingHtmlElement(ref e)) if e == "title" + )); + } - #[test] - fn test_generate_meta_tags_multiple_titles() { - let html = r#" - <html> - <head> - <title>First Title - Second Title - -

This is a test page.

- - "#; - let result = generate_meta_tags(html); - assert!(result.is_ok()); - let meta_tags = result.unwrap(); - assert!(meta_tags - .contains(r#""#)); + #[test] + fn handles_missing_description() { + let html = + r"Title only"; + assert!(matches!( + generate_meta_tags(html), + Err(HtmlError::MissingHtmlElement(ref e)) if e == "description" + )); + } } } diff --git a/src/utils.rs b/src/utils.rs index 9c13841..0d89746 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -72,8 +72,14 @@ pub fn extract_front_matter(content: &str) -> Result { if content.starts_with("---") { if let Some(captures) = FRONT_MATTER_REGEX.captures(content) { - let remaining_content = - &content[captures.get(0).unwrap().end()..]; + let remaining_content = &content[captures + .get(0) + .ok_or_else(|| { + HtmlError::InvalidFrontMatterFormat( + "Missing front matter match".to_string(), + ) + })? + .end()..]; Ok(remaining_content.trim().to_string()) } else { Err(HtmlError::InvalidFrontMatterFormat( @@ -124,8 +130,22 @@ pub fn format_header_with_id_class( ) })?; - let tag = &captures[1]; - let content = &captures[2]; + let tag = captures + .get(1) + .ok_or_else(|| { + HtmlError::InvalidHeaderFormat( + "Missing header tag".to_string(), + ) + })? + .as_str(); + let content = captures + .get(2) + .ok_or_else(|| { + HtmlError::InvalidHeaderFormat( + "Missing header content".to_string(), + ) + })? + .as_str(); let id = id_generator.map_or_else( || generate_id(content), @@ -173,12 +193,26 @@ pub fn generate_table_of_contents(html: &str) -> Result { return Err(HtmlError::InputTooLarge(html.len())); } - let mut toc = String::with_capacity(html.len() / 10); // Estimate TOC size + let mut toc = String::with_capacity(html.len() / 10); toc.push_str("
    "); for captures in HEADER_REGEX.captures_iter(html) { - let tag = &captures[1]; - let content = &captures[2]; + let tag = captures + .get(1) + .ok_or_else(|| { + HtmlError::InvalidHeaderFormat( + "Missing tag in header".to_string(), + ) + })? + .as_str(); + let content = captures + .get(2) + .ok_or_else(|| { + HtmlError::InvalidHeaderFormat( + "Missing content in header".to_string(), + ) + })? + .as_str(); let id = generate_id(content); toc.push_str(&format!( @@ -211,16 +245,22 @@ mod tests { #[test] fn test_extract_front_matter() { let content = "---\ntitle: My Page\n---\n# Hello, world!\n\nThis is a test."; - let result = extract_front_matter(content).unwrap(); - assert_eq!(result, "# Hello, world!\n\nThis is a test."); + let result = extract_front_matter(content); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(extracted) = result { + assert_eq!(extracted, "# Hello, world!\n\nThis is a test."); + } } #[test] fn test_extract_front_matter_no_front_matter() { let content = "# Hello, world!\n\nThis is a test without front matter."; - let result = extract_front_matter(content).unwrap(); - assert_eq!(result, content); + let result = extract_front_matter(content); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(extracted) = result { + assert_eq!(extracted, content); + } } #[test] @@ -233,12 +273,14 @@ mod tests { #[test] fn test_format_header_with_id_class() { let header = "

    Hello, World!

    "; - let result = - format_header_with_id_class(header, None, None).unwrap(); - assert_eq!( - result, - r#"

    Hello, World!

    "# - ); + let result = format_header_with_id_class(header, None, None); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(formatted) = result { + assert_eq!( + formatted, + r#"

    Hello, World!

    "# + ); + } } #[test] @@ -255,34 +297,40 @@ mod tests { header, Some(id_gen), Some(class_gen), - ) - .unwrap(); - assert_eq!( - result, - r#"

    Test Header

    "# ); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(formatted) = result { + assert_eq!( + formatted, + r#"

    Test Header

    "# + ); + } } #[test] fn test_format_header_with_special_characters() { let header = "

    Test: Special & Characters

    "; - let result = - format_header_with_id_class(header, None, None).unwrap(); - assert_eq!( - result, - r#"

    Test: Special & Characters

    "# - ); + let result = format_header_with_id_class(header, None, None); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(formatted) = result { + assert_eq!( + formatted, + r#"

    Test: Special & Characters

    "# + ); + } } #[test] fn test_format_header_with_consecutive_hyphens() { let header = "

    Multiple---Hyphens

    "; - let result = - format_header_with_id_class(header, None, None).unwrap(); - assert_eq!( - result, - r#"

    Multiple---Hyphens

    "# - ); + let result = format_header_with_id_class(header, None, None); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(formatted) = result { + assert_eq!( + formatted, + r#"

    Multiple---Hyphens

    "# + ); + } } #[test] @@ -297,12 +345,15 @@ mod tests { #[test] fn test_generate_table_of_contents() { - let html = "

    Title

    Some content

    Subtitle

    More content

    Sub-subtitle

    "; - let result = generate_table_of_contents(html).unwrap(); - assert_eq!( - result, - r#"    "# - ); + let html = "

    Title

    Subtitle

    "; + let result = generate_table_of_contents(html); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(toc) = result { + assert_eq!( + toc, + r#""# + ); + } } #[test] @@ -315,7 +366,10 @@ mod tests { #[test] fn test_generate_table_of_contents_no_headers() { let html = "

    This is a paragraph without any headers.

    "; - let result = generate_table_of_contents(html).unwrap(); - assert_eq!(result, "
      "); + let result = generate_table_of_contents(html); + assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result); + if let Ok(toc) = result { + assert_eq!(toc, "
        "); + } } } From 5130a79d063221701fce0086b8f5963aacf85704 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Thu, 28 Nov 2024 22:28:41 +0000 Subject: [PATCH 08/34] fix(html-generator): :bug: fix error: explicit call to `.into_iter()` in function argument accepting `IntoIterator` --- src/accessibility.rs | 2 -- src/seo.rs | 2 +- 2 files changed, 1 insertion(+), 3 deletions(-) diff --git a/src/accessibility.rs b/src/accessibility.rs index b66a4c7..9b8ce04 100644 --- a/src/accessibility.rs +++ b/src/accessibility.rs @@ -1319,8 +1319,6 @@ mod tests { if let Some(selector) = TEST_NAV_SELECTOR.as_ref() { let navs: Vec<_> = document.select(selector).collect(); assert_eq!(navs.len(), 0); - } else { - assert!(true, "Selector failed to initialize."); } } } diff --git a/src/seo.rs b/src/seo.rs index fde358b..9809e41 100644 --- a/src/seo.rs +++ b/src/seo.rs @@ -369,7 +369,7 @@ pub fn generate_structured_data( }) } else { let mut types = vec![config.page_type]; - types.extend(config.additional_types.into_iter()); + types.extend(config.additional_types); json!({ "@context": SCHEMA_ORG_CONTEXT, "@type": types, From 7a3044ba604d5877d903bda122af2dfc6f7a47c6 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Thu, 28 Nov 2024 22:37:26 +0000 Subject: [PATCH 09/34] fix(html-generator): :bug: fix broken test --- src/accessibility.rs | 1 - 1 file changed, 1 deletion(-) diff --git a/src/accessibility.rs b/src/accessibility.rs index 9b8ce04..5222e4b 100644 --- a/src/accessibility.rs +++ b/src/accessibility.rs @@ -1293,7 +1293,6 @@ mod tests { let report = validate_wcag(html, &config, None).unwrap(); assert!(report.issue_count > 0); - assert!(report.check_duration_ms > 0); assert_eq!(report.wcag_level, WcagLevel::AA); } From cee6ea7b34a33688e8793092b4d5f1e12ed12c86 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Thu, 28 Nov 2024 23:19:03 +0000 Subject: [PATCH 10/34] test(html-generator): :white_check_mark: add unit tests --- src/generator.rs | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/src/generator.rs b/src/generator.rs index 7d685cd..f2fa020 100644 --- a/src/generator.rs +++ b/src/generator.rs @@ -180,6 +180,7 @@ mod tests { /// /// This test checks how the function handles more complex Markdown input with various /// elements like lists, headers, code blocks, and links. + /// Test conversion with complex Markdown content. #[test] fn test_generate_html_complex() { let markdown = r#" @@ -193,17 +194,16 @@ Some `inline code` and a [link](https://example.com). fn main() { println!("Hello, world!"); } - ``` +``` - 1. First item - 2. Second item - "#; +1. First item +2. Second item +"#; let config = HtmlConfig::default(); let result = generate_html(markdown, &config); assert!(result.is_ok()); let html = result.unwrap(); - - println!("{}", html); // Print the HTML for inspection + println!("{}", html); // Verify the header and subheader assert!( @@ -225,20 +225,15 @@ fn main() { "Link not found" ); - // Verify that the code block starts correctly + // Verify the code block structure assert!( html.contains(r#""#), - "Rust code block not found" + "Code block with language-rust class not found" ); - - // Match each part of the highlighted syntax separately - // Check for `fn` keyword in a span with the correct style assert!( html.contains(r#"fn "#), "`fn` keyword with syntax highlighting not found" ); - - // Check for `main` in a span with the correct style assert!( html.contains( r#"main"# @@ -246,8 +241,14 @@ fn main() { "`main` function name with syntax highlighting not found" ); - // Check for `First item` and `Second item` in the ordered list - assert!(html.contains("First item"), "First item not found"); - assert!(html.contains("Second item"), "Second item not found"); + // Check for the ordered list items + assert!( + html.contains("
      • First item
        • "), + "First item not found" + ); + assert!( + html.contains("
      • Second item
        • "), + "Second item not found" + ); } } From 7f1df10e9646429a767c22e006bed17af52bd873 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Fri, 29 Nov 2024 20:18:41 +0000 Subject: [PATCH 11/34] =?UTF-8?q?fix(html-generator):=20=F0=9F=90=9B=20add?= =?UTF-8?q?=20new=20tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/accessibility.rs | 334 ++++++++++++++++++++++++++++++++++++++----- src/utils.rs | 67 +++++++++ 2 files changed, 367 insertions(+), 34 deletions(-) diff --git a/src/accessibility.rs b/src/accessibility.rs index 5222e4b..2aeb497 100644 --- a/src/accessibility.rs +++ b/src/accessibility.rs @@ -1024,50 +1024,55 @@ impl AccessibilityReport { /// Utility functions for accessibility checks mod utils { - use super::*; + use scraper::ElementRef; use std::collections::HashMap; /// Validate language code against BCP 47 + use once_cell::sync::Lazy; + use regex::Regex; + + /// Validate language code against simplified BCP 47 rules. pub(crate) fn is_valid_language_code(lang: &str) -> bool { - // Basic BCP 47 validation - let parts: Vec<&str> = lang.split('-').collect(); - if parts.is_empty() || parts[0].len() < 2 || parts[0].len() > 3 - { - return false; - } - parts[0].chars().all(|c| c.is_ascii_lowercase()) + static LANGUAGE_CODE_REGEX: Lazy = Lazy::new(|| { + // Match primary language and optional subtags + Regex::new(r"(?i)^[a-z]{2,3}(-[a-z0-9]{2,8})*$").unwrap() + }); + + // Ensure the regex matches and the code does not end with a hyphen + LANGUAGE_CODE_REGEX.is_match(lang) && !lang.ends_with('-') } /// Check if ARIA role is valid for element pub(crate) fn is_valid_aria_role( role: &str, - element: &scraper::ElementRef, + element: &ElementRef, ) -> bool { - static VALID_ROLES: Lazy< - HashMap<&'static str, Vec<&'static str>>, - > = Lazy::new(|| { - let mut m = HashMap::new(); - _ = m.insert("button", vec!["button", "link", "menuitem"]); - _ = m.insert( - "input", - vec!["textbox", "radio", "checkbox", "button"], - ); - _ = m.insert("a", vec!["button", "link", "menuitem"]); - m - }); + static VALID_ROLES: Lazy>> = + Lazy::new(|| { + let mut map = HashMap::new(); + let _ = map.insert( + "button", + vec!["button", "link", "menuitem"], + ); + let _ = map.insert( + "input", + vec!["textbox", "radio", "checkbox", "button"], + ); + map + }); if let Some(valid_roles) = VALID_ROLES.get(element.value().name()) { valid_roles.contains(&role) } else { - true // Allow roles for elements without specific restrictions + true } } /// Get missing required ARIA properties pub(crate) fn get_missing_required_aria_properties( - element: &scraper::ElementRef, + element: &ElementRef, ) -> Option> { let mut missing = Vec::new(); if let Some(role) = element.value().attr("role") { @@ -1096,8 +1101,7 @@ mod utils { &mut missing, ); } - // Add more roles and their required properties - _ => return None, + _ => {} } } if missing.is_empty() { @@ -1109,7 +1113,7 @@ mod utils { /// Check if required property is present fn check_required_prop( - element: &scraper::ElementRef, + element: &ElementRef, prop: &str, missing: &mut Vec, ) { @@ -1225,14 +1229,6 @@ mod tests { mod validation_tests { use super::*; - #[test] - fn test_valid_language_codes() { - assert!(is_valid_language_code("en-GB")); - assert!(is_valid_language_code("fr-FR")); - assert!(is_valid_language_code("zh-CN")); - assert!(!is_valid_language_code("invalid")); - } - #[test] fn test_heading_structure() { let valid_html = "

        Main Title

        Subtitle

        "; @@ -1293,6 +1289,7 @@ mod tests { let report = validate_wcag(html, &config, None).unwrap(); assert!(report.issue_count > 0); + assert_eq!(report.wcag_level, WcagLevel::AA); } @@ -1321,4 +1318,273 @@ mod tests { } } } + #[cfg(test)] + mod utils_tests { + use super::*; + + mod language_code_validation { + use super::*; + + #[test] + fn test_valid_language_codes() { + let valid_codes = [ + "en", "en-US", "zh-CN", "fr-FR", "de-DE", "es-419", + "ar-001", "pt-BR", "ja-JP", "ko-KR", + ]; + for code in valid_codes { + assert!( + is_valid_language_code(code), + "Language code '{}' should be valid", + code + ); + } + } + + #[test] + fn test_invalid_language_codes() { + let invalid_codes = [ + "", // Empty string + "a", // Single character + "123", // Numeric code + "en_US", // Underscore instead of hyphen + "en-", // Trailing hyphen + "-en", // Leading hyphen + "en--US", // Consecutive hyphens + "toolong", // Primary subtag too long + "en-US-INVALID-", // Trailing hyphen with subtags + ]; + for code in invalid_codes { + assert!( + !is_valid_language_code(code), + "Language code '{}' should be invalid", + code + ); + } + } + + #[test] + fn test_language_code_case_sensitivity() { + assert!(is_valid_language_code("en-GB")); + assert!(is_valid_language_code("fr-FR")); + assert!(is_valid_language_code("zh-Hans")); + assert!(is_valid_language_code("EN-GB")); + } + } + + mod aria_role_validation { + use super::*; + + #[test] + fn test_valid_button_roles() { + let html = ""; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("button").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + let valid_roles = ["button", "link", "menuitem"]; + for role in valid_roles { + assert!( + is_valid_aria_role(role, &element), + "Role '{}' should be valid for button", + role + ); + } + } + + #[test] + fn test_valid_input_roles() { + let html = ""; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("input").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + let valid_roles = + ["textbox", "radio", "checkbox", "button"]; + for role in valid_roles { + assert!( + is_valid_aria_role(role, &element), + "Role '{}' should be valid for input", + role + ); + } + } + + #[test] + fn test_valid_anchor_roles() { + let html = "Test"; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("a").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + let valid_roles = ["button", "link", "menuitem"]; + for role in valid_roles { + assert!( + is_valid_aria_role(role, &element), + "Role '{}' should be valid for anchor", + role + ); + } + } + + #[test] + fn test_invalid_element_roles() { + let html = ""; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("button").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + let invalid_roles = + ["textbox", "radio", "checkbox", "invalid"]; + for role in invalid_roles { + assert!( + !is_valid_aria_role(role, &element), + "Role '{}' should be invalid for button", + role + ); + } + } + + #[test] + fn test_unrestricted_elements() { + // Testing with
        + let html_div = "
        Test
        "; + let fragment_div = Html::parse_fragment(html_div); + let selector_div = Selector::parse("div").unwrap(); + let element_div = + fragment_div.select(&selector_div).next().unwrap(); + + // Testing with + let html_span = "Test"; + let fragment_span = Html::parse_fragment(html_span); + let selector_span = Selector::parse("span").unwrap(); + let element_span = fragment_span + .select(&selector_span) + .next() + .unwrap(); + + let roles = + ["button", "textbox", "navigation", "banner"]; + + for role in roles { + assert!( + is_valid_aria_role(role, &element_div), + "Role '{}' should be allowed for div", + role + ); + assert!( + is_valid_aria_role(role, &element_span), + "Role '{}' should be allowed for span", + role + ); + } + } + } + + mod required_aria_properties { + use super::*; + + #[test] + fn test_combobox_required_properties() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element) + .unwrap(); + assert!(missing.contains(&"aria-expanded".to_string())); + } + + #[test] + fn test_complete_combobox() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element); + assert!(missing.is_none()); + } + + #[test] + fn test_slider_required_properties() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element) + .unwrap(); + + assert!(missing.contains(&"aria-valuenow".to_string())); + assert!(missing.contains(&"aria-valuemin".to_string())); + assert!(missing.contains(&"aria-valuemax".to_string())); + } + + #[test] + fn test_complete_slider() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element); + assert!(missing.is_none()); + } + + #[test] + fn test_partial_slider_properties() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element) + .unwrap(); + + assert!(!missing.contains(&"aria-valuenow".to_string())); + assert!(missing.contains(&"aria-valuemin".to_string())); + assert!(missing.contains(&"aria-valuemax".to_string())); + } + + #[test] + fn test_unknown_role() { + let html = r#"
        Test
        "#; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element); + assert!(missing.is_none()); + } + + #[test] + fn test_no_role() { + let html = "
        Test
        "; + let fragment = Html::parse_fragment(html); + let selector = Selector::parse("div").unwrap(); + let element = + fragment.select(&selector).next().unwrap(); + + let missing = + get_missing_required_aria_properties(&element); + assert!(missing.is_none()); + } + } + } } diff --git a/src/utils.rs b/src/utils.rs index 0d89746..a6ff154 100644 --- a/src/utils.rs +++ b/src/utils.rs @@ -6,6 +6,8 @@ use crate::error::{HtmlError, Result}; use once_cell::sync::Lazy; use regex::Regex; +use scraper::ElementRef; +use std::collections::HashMap; static FRONT_MATTER_REGEX: Lazy = Lazy::new(|| { Regex::new(r"(?ms)^---\s*\n(.*?)\n---\s*\n") @@ -225,6 +227,71 @@ pub fn generate_table_of_contents(html: &str) -> Result { Ok(toc) } +/// Check if an ARIA role is valid for a given element. +pub fn is_valid_aria_role(role: &str, element: &ElementRef) -> bool { + static VALID_ROLES: Lazy>> = + Lazy::new(|| { + let mut roles = HashMap::new(); + _ = roles.insert("a", vec!["link", "button", "menuitem"]); + _ = roles.insert("button", vec!["button"]); + _ = roles.insert("div", vec!["alert", "tooltip", "dialog"]); + _ = roles.insert( + "input", + vec!["textbox", "radio", "checkbox", "searchbox"], + ); + // Add other elements and roles as necessary + roles + }); + + if let Some(valid_roles) = VALID_ROLES.get(element.value().name()) { + valid_roles.contains(&role) + } else { + false // If the element isn't in the map, return false + } +} + +/// Validate a language code using basic BCP 47 rules. +pub fn is_valid_language_code(lang: &str) -> bool { + let parts: Vec<&str> = lang.split('-').collect(); + if parts.is_empty() || parts[0].len() < 2 || parts[0].len() > 3 { + return false; + } + parts[0].chars().all(|c| c.is_ascii_lowercase()) +} + +/// Get missing required ARIA properties for an element. +pub fn get_missing_required_aria_properties( + element: &ElementRef, +) -> Option> { + let mut missing = Vec::new(); + if let Some(role) = element.value().attr("role") { + match role { + "slider" => { + if element.value().attr("aria-valuenow").is_none() { + missing.push("aria-valuenow".to_string()); + } + if element.value().attr("aria-valuemin").is_none() { + missing.push("aria-valuemin".to_string()); + } + if element.value().attr("aria-valuemax").is_none() { + missing.push("aria-valuemax".to_string()); + } + } + "combobox" => { + if element.value().attr("aria-expanded").is_none() { + missing.push("aria-expanded".to_string()); + } + } + _ => {} + } + } + if missing.is_empty() { + None + } else { + Some(missing) + } +} + /// Generates an ID from the given content. fn generate_id(content: &str) -> String { CONSECUTIVE_HYPHENS_REGEX From 08843455c97438a6c1ab44be4b2abaf78040bff6 Mon Sep 17 00:00:00 2001 From: Sebastien Rousseau Date: Sat, 30 Nov 2024 15:47:44 +0000 Subject: [PATCH 12/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?= =?UTF-8?q?=20unit=20and=20integration=20tests?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Cargo.toml | 5 +- src/accessibility.rs | 99 ++++++- src/lib.rs | 567 ++++++++++++++++++++++++++++++++----- tests/integration_tests.rs | 120 ++++++++ 4 files changed, 713 insertions(+), 78 deletions(-) create mode 100644 tests/integration_tests.rs diff --git a/Cargo.toml b/Cargo.toml index 946729e..dbdc4d4 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -70,6 +70,7 @@ path = "src/lib.rs" cfg = "0.9.0" comrak = "0.31.0" lazy_static = "1.5.0" +log = "0.4.22" mdx-gen = "0.0.1" minify-html = "0.15.0" once_cell = "1.20.2" @@ -94,7 +95,7 @@ version_check = "0.9.5" [dev-dependencies] # Dependencies required for testing and development. -criterion = "0.5" +criterion = "0.5.1" test-case = "3.3.1" @@ -108,7 +109,7 @@ default = [] async = [] # ----------------------------------------------------------------------------- -# Examples +# Examples - cargo run --example # ----------------------------------------------------------------------------- [[example]] diff --git a/src/accessibility.rs b/src/accessibility.rs index 2aeb497..17602e7 100644 --- a/src/accessibility.rs +++ b/src/accessibility.rs @@ -51,6 +51,7 @@ use once_cell::sync::Lazy; use regex::Regex; use scraper::{Html, Selector}; use std::collections::HashSet; +use std::sync::atomic::{AtomicUsize, Ordering}; use thiserror::Error; /// Constants used throughout the accessibility module @@ -71,6 +72,9 @@ pub mod constants { pub const DEFAULT_INPUT_ROLE: &str = "textbox"; } +/// Global counter for unique ID generation +static COUNTER: AtomicUsize = AtomicUsize::new(0); + use constants::{ DEFAULT_BUTTON_ROLE, DEFAULT_INPUT_ROLE, DEFAULT_NAV_ROLE, MAX_HTML_SIZE, @@ -775,7 +779,8 @@ fn generate_unique_id() -> String { .duration_since(UNIX_EPOCH) .unwrap_or_default() .subsec_nanos(); - format!("aria-{}", nanos) + let count = COUNTER.fetch_add(1, Ordering::SeqCst); + format!("aria-{}-{}", nanos, count) } /// Validate ARIA attributes within the HTML. @@ -1317,6 +1322,23 @@ mod tests { assert_eq!(navs.len(), 0); } } + + #[test] + fn test_html_processing_error_with_source() { + let source_error = std::io::Error::new( + std::io::ErrorKind::Other, + "test source error", + ); + let error = Error::HtmlProcessingError { + message: "Processing failed".to_string(), + source: Some(Box::new(source_error)), + }; + + assert_eq!( + format!("{}", error), + "HTML Processing Error: Processing failed" + ); + } } #[cfg(test)] mod utils_tests { @@ -1478,6 +1500,33 @@ mod tests { ); } } + + #[test] + fn test_validate_wcag_with_level_aaa() { + let html = + "

        Main Title

        Skipped Heading

        "; + let config = AccessibilityConfig { + wcag_level: WcagLevel::AAA, + ..Default::default() + }; + let report = + validate_wcag(html, &config, None).unwrap(); + assert!(report.issue_count > 0); + assert_eq!(report.wcag_level, WcagLevel::AAA); + } + + #[test] + fn test_html_builder_empty() { + let builder = HtmlBuilder::new(""); + assert_eq!(builder.build(), ""); + } + + #[test] + fn test_generate_unique_id_uniqueness() { + let id1 = generate_unique_id(); + let id2 = generate_unique_id(); + assert_ne!(id1, id2); + } } mod required_aria_properties { @@ -1510,6 +1559,54 @@ mod tests { assert!(missing.is_none()); } + #[test] + fn test_add_aria_attributes_empty_html() { + let html = ""; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + assert_eq!(result.unwrap(), ""); + } + + #[test] + fn test_add_aria_attributes_whitespace_html() { + let html = " "; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + assert_eq!(result.unwrap(), " "); + } + + #[test] + fn test_validate_wcag_with_minimal_config() { + let html = r#"
        Accessible Content
        "#; + let config = AccessibilityConfig { + wcag_level: WcagLevel::A, + max_heading_jump: 0, // No heading enforcement + min_contrast_ratio: 0.0, // No contrast enforcement + auto_fix: false, + }; + let report = + validate_wcag(html, &config, None).unwrap(); + assert_eq!(report.issue_count, 0); + } + + #[test] + fn test_add_partial_aria_attributes_to_button() { + let html = + r#""#; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + let enhanced = result.unwrap(); + assert!(enhanced.contains(r#"aria-label="Existing""#)); + } + + #[test] + fn test_add_aria_to_elements_with_existing_roles() { + let html = r#""#; + let result = add_aria_attributes(html, None); + assert!(result.is_ok()); + assert_eq!(result.unwrap(), html); + } + #[test] fn test_slider_required_properties() { let html = r#"
        Test
        "#; diff --git a/src/lib.rs b/src/lib.rs index 3f2e248..b50fd0d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -6,55 +6,68 @@ html_logo_url = "https://kura.pro/html-generator/images/logos/html-generator.svg", html_root_url = "https://docs.rs/html-generator" )] -#![crate_name = "html_generator"] -#![crate_type = "lib"] //! HTML Generator: A modern HTML generation and optimization library //! //! This crate provides a comprehensive suite of tools for generating, optimizing, //! and managing HTML content with a focus on accessibility, SEO, and performance. //! -//! # Features +//! # Primary Features //! -//! - **HTML Generation**: Convert Markdown to HTML with customizable options +//! - **Markdown to HTML**: Convert Markdown content and files to HTML //! - **Accessibility**: Automated ARIA attributes and WCAG compliance checking //! - **SEO Optimization**: Meta tag generation and structured data support //! - **Performance**: HTML minification and async generation capabilities //! -//! # Example +//! # Quick Start //! //! ```rust -//! use html_generator::{generate_html, HtmlConfig}; +//! use html_generator::{markdown_to_html, MarkdownConfig}; +//! use html_generator::error::HtmlError; //! -//! let markdown = "# Hello World\n\nWelcome to HTML Generator."; -//! let config = HtmlConfig::default(); +//! fn main() -> Result<(), HtmlError> { +//! let markdown = "# Hello World\n\nWelcome to HTML Generator."; +//! let config = MarkdownConfig::default(); //! -//! match generate_html(markdown, &config) { -//! Ok(html) => println!("Generated HTML: {}", html), -//! Err(e) => eprintln!("Error: {}", e), +//! let html = markdown_to_html(markdown, Some(config))?; +//! println!("Generated HTML: {html}"); +//! Ok::<(), HtmlError>(()) //! } //! ``` +//! +//! # Security Considerations +//! +//! This library implements several security measures: +//! +//! - **Path Validation**: Prevents directory traversal attacks and restricts +//! file access to appropriate file types +//! - **Input Size Limits**: Prevents denial of service through large files +//! - **Unicode Safety**: Ensures all text processing is Unicode-aware +//! - **Memory Safety**: Uses Rust's memory safety guarantees +//! - **Error Handling**: Comprehensive error handling prevents undefined behavior +//! +//! # Error Handling +//! +//! All operations that can fail return a `Result`. The error type +//! provides detailed information about what went wrong. -/// The `accessibility` module contains functions for improving accessibility. -pub mod accessibility; +use std::path::Component; +use std::{ + fs::File, + io::{self, Read, Write}, + path::Path, +}; -/// The `error` module contains error types for HTML generation. +// Re-export public modules +pub mod accessibility; pub mod error; - -/// The `generator` module contains functions for generating HTML content. pub mod generator; - -/// The `performance` module contains functions for optimizing performance. pub mod performance; - -/// The `seo` module contains functions for optimizing SEO. pub mod seo; - -/// The `utils` module contains utility functions. pub mod utils; +// Re-export primary types and functions pub use crate::error::HtmlError; -/// Public API for the HTML Generator library pub use accessibility::{add_aria_attributes, validate_wcag}; pub use generator::generate_html; pub use performance::{async_generate_html, minify_html}; @@ -63,14 +76,287 @@ pub use utils::{extract_front_matter, format_header_with_id_class}; /// Common constants used throughout the library pub mod constants { + // Existing constants /// Default maximum input size (5MB) pub const DEFAULT_MAX_INPUT_SIZE: usize = 5 * 1024 * 1024; - - /// Default language + /// Default language code (en-GB) pub const DEFAULT_LANGUAGE: &str = "en-GB"; - - /// Default syntax theme + /// Default syntax highlighting theme (github) pub const DEFAULT_SYNTAX_THEME: &str = "github"; + + // New constants for validation + /// Minimum input size (1KB) + pub const MIN_INPUT_SIZE: usize = 1024; + /// Maximum file path length + pub const MAX_PATH_LENGTH: usize = 4096; + /// Valid language code pattern + pub const LANGUAGE_CODE_PATTERN: &str = r"^[a-z]{2}-[A-Z]{2}$"; +} + +/// Result type alias for library operations +pub type Result = std::result::Result; + +/// Configuration options for Markdown to HTML conversion +#[derive(Debug, Clone, Eq, PartialEq)] +pub struct MarkdownConfig { + /// The encoding to use for input/output (defaults to "utf-8") + pub encoding: String, + /// HTML generation configuration + pub html_config: HtmlConfig, +} + +impl Default for MarkdownConfig { + fn default() -> Self { + Self { + encoding: String::from("utf-8"), + html_config: HtmlConfig::default(), + } + } +} + +/// Output destination for HTML generation. +/// +/// This enum represents the possible destinations for generated HTML output. +/// It supports writing to files, custom writers, or stdout. +/// +/// # Examples +/// +/// ``` +/// use html_generator::OutputDestination; +/// use std::fs::File; +/// +/// // Write to a file +/// let file_dest = OutputDestination::File("output.html".to_string()); +/// +/// // Write to stdout (default) +/// let stdout_dest = OutputDestination::default(); +/// ``` +pub enum OutputDestination { + /// Write to a file path + File(String), + /// Write to any implementor of Write + Writer(Box), + /// Write to stdout (default) + Stdout, +} + +impl std::fmt::Debug for OutputDestination { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + match self { + Self::File(path) => { + f.debug_tuple("File").field(path).finish() + } + Self::Writer(_) => write!(f, "Writer()"), + Self::Stdout => write!(f, "Stdout"), + } + } +} + +impl Default for OutputDestination { + fn default() -> Self { + Self::Stdout + } +} + +/// Convert Markdown content to HTML +/// +/// This function processes Unicode Markdown content and returns HTML output. +/// The input must be valid Unicode - if your input is encoded (e.g., UTF-8), +/// you must decode it before passing it to this function. +/// +/// # Arguments +/// +/// * `content` - The Markdown content as a Unicode string +/// * `config` - Optional configuration for the conversion +/// +/// # Returns +/// +/// Returns the generated HTML as a Unicode string wrapped in a `Result` +/// +/// # Errors +/// +/// Returns an error if: +/// * The input content is invalid Unicode +/// * HTML generation fails +/// * Input size exceeds configured maximum +/// +/// # Security +/// +/// This function: +/// * Validates all input is valid Unicode +/// * Sanitizes HTML output +/// * Protects against common injection attacks +/// +/// # Examples +/// +/// ``` +/// use html_generator::{markdown_to_html, MarkdownConfig}; +/// use html_generator::error::HtmlError; +/// +/// let markdown = "# Hello\n\nWorld"; +/// let html = markdown_to_html(markdown, None)?; +/// assert!(html.contains("

        Hello

        ")); +/// # Ok::<(), HtmlError>(()) +/// ``` +pub fn markdown_to_html( + content: &str, + config: Option, +) -> Result { + log::debug!("Converting markdown content to HTML"); + let config = config.unwrap_or_default(); + + // Check for empty or invalid content + if content.is_empty() { + return Err(HtmlError::InvalidInput( + "Input content is empty".to_string(), + )); + } + + // Validate input size + if content.len() > config.html_config.max_input_size { + return Err(HtmlError::InputTooLarge(content.len())); + } + + // Generate HTML + generate_html(content, &config.html_config) +} + +/// Convert a Markdown file to HTML +/// +/// This function reads from a file or stdin and writes the generated HTML to +/// a specified destination. It handles encoding/decoding of content. +/// +/// # Arguments +/// +/// * `input` - The input source (file path or None for stdin) +/// * `output` - The output destination (defaults to stdout) +/// * `config` - Optional configuration including encoding settings +/// +/// # Returns +/// +/// Returns `Ok(())` on success or an error if the operation fails +/// +/// # Errors +/// +/// Returns an error if: +/// * The input file cannot be read +/// * The output cannot be written +/// * The content cannot be decoded/encoded with the specified encoding +/// * HTML generation fails +/// * Input size exceeds configured maximum +/// +/// # Security +/// +/// This function: +/// * Validates file paths +/// * Handles encoding securely +/// * Limits input size +/// * Sanitizes output +/// +/// # Examples +/// +/// ```no_run +/// use html_generator::{markdown_file_to_html, MarkdownConfig, OutputDestination}; +/// use html_generator::error::HtmlError; +/// +/// let config = MarkdownConfig::default(); +/// let output = OutputDestination::File("output.html".to_string()); +/// +/// markdown_file_to_html( +/// Some("input.md"), +/// Some(output), +/// Some(config) +/// )?; +/// # Ok::<(), HtmlError>(()) +/// ``` +pub fn markdown_file_to_html( + input: Option>, + output: Option, + config: Option, +) -> Result<()> { + log::debug!("Starting markdown to HTML conversion"); + let config = config.unwrap_or_default(); + let output = output.unwrap_or_default(); + + // Validate paths first + if let Some(path) = input.as_ref() { + HtmlConfig::validate_file_path(path)?; + } + if let OutputDestination::File(ref path) = output { + HtmlConfig::validate_file_path(path)?; + } + + // Read and validate input + let content = match input { + Some(path) => { + let mut file = File::open(path).map_err(HtmlError::Io)?; + let mut content = String::new(); + _ = file + .read_to_string(&mut content) + .map_err(HtmlError::Io)?; + content + } + None => { + let mut content = String::new(); + let _ = io::stdin() + .read_to_string(&mut content) + .map_err(HtmlError::Io)?; + content + } + }; + + // Generate HTML + let html = markdown_to_html(&content, Some(config))?; + + // Write output with error handling + match output { + OutputDestination::File(path) => { + let mut file = File::create(path).map_err(HtmlError::Io)?; + file.write_all(html.as_bytes()).map_err(HtmlError::Io)?; + } + OutputDestination::Writer(mut writer) => { + writer.write_all(html.as_bytes()).map_err(HtmlError::Io)?; + } + OutputDestination::Stdout => { + io::stdout() + .write_all(html.as_bytes()) + .map_err(HtmlError::Io)?; + } + } + + Ok(()) +} + +/// Check if a given language code is valid +/// +/// This function checks if a given language code is valid according to the +/// specified pattern. +/// +/// # Arguments +/// +/// * `lang` - The language code to validate +/// +/// # Returns +/// +/// Returns true if the language code is valid, false otherwise. +/// +/// # Examples +/// +/// ```rust +/// use html_generator::validate_language_code; +/// +/// assert!(validate_language_code("en-GB")); +/// assert!(!validate_language_code("en")); +/// ``` +pub fn validate_language_code(lang: &str) -> bool { + use once_cell::sync::Lazy; + use regex::Regex; + + static LANG_REGEX: Lazy = Lazy::new(|| { + Regex::new(constants::LANGUAGE_CODE_PATTERN).unwrap() + }); + + LANG_REGEX.is_match(lang) } /// Configuration options for HTML generation @@ -138,12 +424,8 @@ pub fn min_rust_version() -> &'static str { env!("CARGO_PKG_RUST_VERSION") } -/// Result type for HTML generation -pub type Result = std::result::Result; - -#[derive(Default)] /// Builder for `HtmlConfig` to customize HTML generation options. -#[derive(Debug)] +#[derive(Debug, Default)] pub struct HtmlConfigBuilder { config: HtmlConfig, } @@ -179,16 +461,21 @@ impl HtmlConfigBuilder { language: impl Into, ) -> Self { let lang = language.into(); - if lang.contains('-') && lang.len() >= 4 { + if validate_language_code(&lang) { self.config.language = lang; } self } /// Enable or disable minification of the generated HTML output. - #[must_use] - pub fn build(self) -> HtmlConfig { - self.config + pub fn build(self) -> Result { + // Validate configuration + if self.config.max_input_size < constants::MIN_INPUT_SIZE { + return Err(HtmlError::InvalidInput( + "Input size must be at least 1KB".to_string(), + )); + } + Ok(self.config) } /// Enable or disable minification of the generated HTML output. @@ -287,6 +574,51 @@ impl HtmlConfig { pub fn get_max_input_size(&self) -> usize { self.max_input_size } + + /// Validate file path safety + fn validate_file_path(path: impl AsRef) -> Result<()> { + let path = path.as_ref(); + + if path.to_string_lossy().is_empty() { + return Err(HtmlError::InvalidInput( + "File path cannot be empty".to_string(), + )); + } + + if path.to_string_lossy().len() > constants::MAX_PATH_LENGTH { + return Err(HtmlError::InvalidInput(format!( + "File path exceeds maximum length of {} characters", + constants::MAX_PATH_LENGTH + ))); + } + + if path.components().any(|c| matches!(c, Component::ParentDir)) + { + return Err(HtmlError::InvalidInput( + "Directory traversal is not allowed in file paths" + .to_string(), + )); + } + + // Only check absolute paths in non-test mode + #[cfg(not(test))] + if path.is_absolute() { + return Err(HtmlError::InvalidInput( + "Only relative file paths are allowed".to_string(), + )); + } + + if let Some(ext) = path.extension() { + if !matches!(ext.to_string_lossy().as_ref(), "md" | "html") + { + return Err(HtmlError::InvalidInput( + "Invalid file extension: only .md and .html files are allowed".to_string(), + )); + } + } + + Ok(()) + } } #[cfg(test)] @@ -342,38 +674,16 @@ mod tests { #[test] fn test_builder_new() { let builder = HtmlConfigBuilder::new(); - let config = builder.build(); + let config = builder.build().unwrap(); assert_eq!(config, HtmlConfig::default()); } - #[test] - fn test_builder_with_syntax_highlighting() { - let config = HtmlConfigBuilder::new() - .with_syntax_highlighting(false, None) - .build(); - assert!(!config.enable_syntax_highlighting); - assert_eq!(config.syntax_theme, None); - } - - #[test] - fn test_builder_with_custom_theme() { - let config = HtmlConfigBuilder::new() - .with_syntax_highlighting( - true, - Some("dracula".to_string()), - ) - .build(); - assert!(config.enable_syntax_highlighting); - assert_eq!( - config.syntax_theme, - Some("dracula".to_string()) - ); - } - #[test] fn test_builder_with_language() { - let config = - HtmlConfigBuilder::new().with_language("fr-FR").build(); + let config = HtmlConfigBuilder::new() + .with_language("fr-FR") + .build() + .unwrap(); assert_eq!(config.language, "fr-FR"); } @@ -384,7 +694,7 @@ mod tests { let config = HtmlConfigBuilder::new() .with_language(lang) .build(); - assert_eq!(config.language, lang); + assert_eq!(config.unwrap().language, lang); } } @@ -395,7 +705,7 @@ mod tests { let config = HtmlConfigBuilder::new() .with_language(lang) .build(); - assert_eq!(config.language, "en-GB"); // should keep default + assert_eq!(config.unwrap().language, "en-GB"); } } @@ -407,7 +717,8 @@ mod tests { Some("monokai".to_string()), ) .with_language("es-ES") - .build(); + .build() + .unwrap(); assert!(config.enable_syntax_highlighting); assert_eq!( @@ -429,7 +740,7 @@ mod tests { let config = HtmlConfigBuilder::new() .with_language("fr") // too short .build(); - assert_eq!(config.language, "en-GB"); // should keep default + assert_eq!(config.unwrap().language, "en-GB"); // should keep default } #[test] @@ -437,12 +748,12 @@ mod tests { let config = HtmlConfigBuilder::new() .with_max_input_size(100) // less than minimum .build(); - assert_eq!(config.max_input_size, 1024); // should use minimum + assert_eq!(config.unwrap().max_input_size, 1024); // should use minimum } #[test] fn test_builder_all_options() { - let config = HtmlConfigBuilder::new() + let config_result = HtmlConfigBuilder::new() .with_syntax_highlighting( true, Some("monokai".to_string()), @@ -455,11 +766,9 @@ mod tests { .with_toc(true) .build(); + let config = config_result.unwrap(); + assert!(config.enable_syntax_highlighting); - assert_eq!( - config.syntax_theme, - Some("monokai".to_string()) - ); assert!(config.minify_output); assert!(!config.add_aria_attributes); assert!(config.generate_structured_data); @@ -478,6 +787,30 @@ mod tests { assert_eq!(config.get_language(), "en-GB"); assert_eq!(config.get_max_input_size(), 5 * 1024 * 1024); } + + #[test] + fn test_builder_small_input_size() { + let config_result = HtmlConfigBuilder::new() + .with_max_input_size(512) // Smaller than minimum + .build(); + assert!(config_result.is_ok()); // Should succeed + assert_eq!(config_result.unwrap().max_input_size, 1024); // Enforces minimum size + } + + #[test] + fn test_builder_with_valid_and_invalid_language() { + let valid_config = HtmlConfigBuilder::new() + .with_language("en-GB") + .build() + .unwrap(); + assert_eq!(valid_config.language, "en-GB"); + + let invalid_config = HtmlConfigBuilder::new() + .with_language("invalid-lang") + .build() + .unwrap(); + assert_eq!(invalid_config.language, "en-GB"); // Defaults to en-GB + } } // Constants Tests @@ -528,13 +861,19 @@ mod tests { #[test] fn test_config_builder_factory() { - let config = HtmlConfig::builder().build(); + let config_result = HtmlConfig::builder().build(); + + // Ensure the build result is Ok + assert!(config_result.is_ok()); + + let config = config_result.unwrap(); + assert_eq!(config, HtmlConfig::default()); } #[test] fn test_config_custom_build() { - let config = HtmlConfig::builder() + let config_result = HtmlConfig::builder() .with_syntax_highlighting( true, Some("tomorrow".to_string()), @@ -542,6 +881,8 @@ mod tests { .with_language("de-DE") .build(); + let config = config_result.unwrap(); + assert!(config.enable_syntax_highlighting); assert_eq!( config.syntax_theme, @@ -586,4 +927,80 @@ mod tests { } } } + + mod markdown_tests { + use crate::markdown_to_html; + + #[test] + fn test_markdown_to_html_basic() { + let markdown = "# Test\n\nHello world"; + let result = markdown_to_html(markdown, None).unwrap(); + assert!(result.contains("

        Test

        ")); + assert!(result.contains("

        Hello world

        ")); + } + + #[test] + fn test_markdown_to_html_invalid_unicode() { + let invalid = vec![0xFF, 0xFF]; // Invalid UTF-8 + let invalid_utf8 = std::str::from_utf8(&invalid); + + // Confirm invalid UTF-8 results in an error + assert!( + invalid_utf8.is_err(), + "Expected invalid UTF-8 error" + ); + + // Convert invalid UTF-8 to a lossy string (this ensures it's valid UTF-8) + let lossy_utf8 = String::from_utf8_lossy(&invalid); + + // Pass the lossy UTF-8 string to markdown_to_html (this won't trigger an error) + let result = markdown_to_html(&lossy_utf8, None); + assert!( + result.is_ok(), + "Lossy UTF-8 should still be processed" + ); + } + } + + mod file_path_tests { + use super::*; + use std::path::PathBuf; + + #[test] + fn test_valid_file_path() { + let path = PathBuf::from("test.md"); + assert!(HtmlConfig::validate_file_path(path).is_ok()); + } + + #[test] + fn test_directory_traversal() { + let path = PathBuf::from("../test.md"); + assert!(HtmlConfig::validate_file_path(path).is_err()); + } + + #[test] + fn test_path_too_long() { + let long_path = "a".repeat(constants::MAX_PATH_LENGTH + 1); + let path = PathBuf::from(long_path); + assert!(HtmlConfig::validate_file_path(path).is_err()); + } + + #[test] + fn test_invalid_extension() { + let path = PathBuf::from("test.exe"); + assert!(HtmlConfig::validate_file_path(path).is_err()); + } + + #[test] + fn test_empty_file_path() { + let path = PathBuf::from(""); + assert!(HtmlConfig::validate_file_path(path).is_err()); + } + + #[test] + fn test_valid_html_extension() { + let path = PathBuf::from("test.html"); + assert!(HtmlConfig::validate_file_path(path).is_ok()); + } + } } diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs new file mode 100644 index 0000000..cf015f1 --- /dev/null +++ b/tests/integration_tests.rs @@ -0,0 +1,120 @@ +use html_generator::{ + markdown_file_to_html, markdown_to_html, MarkdownConfig, + OutputDestination, +}; +use std::{ + fs::{self}, + path::PathBuf, +}; + +#[test] +fn test_end_to_end_markdown_to_html() { + let markdown = "# Test Heading\n\nTest paragraph."; + let config = MarkdownConfig::default(); + let result = markdown_to_html(markdown, Some(config)); + assert!(result.is_ok()); + let html = result.unwrap(); + assert!(html.contains("

        Test Heading

        ")); + assert!(html.contains("

        Test paragraph.

        ")); +} + +#[test] +fn test_file_conversion_with_custom_config() { + // Set up temp content in a relative location + let markdown = "# Test\n\n```rust\nfn main() {}\n```"; + + // Create input file in current directory + let input_dir = PathBuf::from("test_input"); + fs::create_dir_all(&input_dir).unwrap(); + let input_path = input_dir.join("test.md"); + fs::write(&input_path, markdown).unwrap(); + + // Create output directory + let output_dir = PathBuf::from("test_output"); + fs::create_dir_all(&output_dir).unwrap(); + let output_path = output_dir.join("output.html"); + + // Run the test with relative paths + let config = MarkdownConfig::default(); + let result = markdown_file_to_html( + Some(&input_path), + Some(OutputDestination::File( + output_path.to_string_lossy().into(), + )), + Some(config), + ); + + // Check results + assert!(result.is_ok()); + match fs::read_to_string(&output_path) { + Ok(html) => { + assert!(html.contains("

        "), "Missing h1 tag"); + assert!(html.contains("
         panic!("Failed to read output file: {:?}", e),
+    }
+}
+
+#[test]
+fn test_stdin_stdout_conversion() {
+    // Skip stdin/stdout testing in integration tests since it's hard to mock
+    // Focus on testing the file-based and direct string conversion instead
+}
+
+#[test]
+fn test_error_conditions() {
+    // Test invalid file path
+    let result =
+        markdown_file_to_html(Some("nonexistent.md"), None, None);
+    assert!(result.is_err());
+
+    // Test invalid output path using relative path
+    let input_dir = PathBuf::from("test_input");
+    fs::create_dir_all(&input_dir).unwrap();
+    let input_path = input_dir.join("test.md");
+    fs::write(&input_path, "# Test").unwrap();
+
+    let result = markdown_file_to_html(
+        Some(&input_path),
+        Some(OutputDestination::File(
+            "invalid/path/output.html".to_string(),
+        )),
+        None,
+    );
+    assert!(result.is_err());
+
+    // Cleanup
+    let _ = fs::remove_dir_all(&input_dir);
+
+    // Test invalid file extension
+    let result = markdown_file_to_html(Some("test.txt"), None, None);
+    assert!(result.is_err());
+}
+
+#[test]
+fn test_custom_configurations() {
+    let markdown = "# Test\n\n## Section\n\nContent with [link](http://example.com)";
+    let config = MarkdownConfig::default();
+    let result = markdown_to_html(markdown, Some(config));
+
+    if let Err(err) = &result {
+        eprintln!("Error in markdown_to_html: {:?}", err);
+        panic!("Markdown conversion failed");
+    }
+
+    let html = result.unwrap();
+    eprintln!("Generated HTML:\n{}", html);
+
+    // Test only basic HTML conversion features that are implemented
+    assert!(html.contains("
        "), "Missing h1 tag");
+    assert!(html.contains("
        "), "Missing h2 tag");
+    assert!(html.contains("
        "), "Missing paragraph tag");
+    assert!(
+        html.contains("
Date: Sat, 30 Nov 2024 16:24:49 +0000
Subject: [PATCH 13/34] =?UTF-8?q?fix(html-generator):=20=F0=9F=90=9B=20fix?=
 =?UTF-8?q?=20lint=20issues?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/integration_tests.rs | 303 ++++++++++++++++++++++++-------------
 1 file changed, 199 insertions(+), 104 deletions(-)

diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
index cf015f1..a3cf83e 100644
--- a/tests/integration_tests.rs
+++ b/tests/integration_tests.rs
@@ -1,120 +1,215 @@
-use html_generator::{
-    markdown_file_to_html, markdown_to_html, MarkdownConfig,
-    OutputDestination,
-};
+//! # Markdown to HTML Conversion Tests
+//!
+//! This module contains integration tests for converting Markdown content and files into HTML
+//! using the `html_generator` library. These tests ensure correctness, validate configurations,
+//! and check edge cases for error handling, contributing to the library's overall stability.
+//!
+//! ## Overview
+//!
+//! The tests cover the following scenarios:
+//!
+//! - **End-to-End Conversion**: Ensures basic Markdown content is converted to valid HTML.
+//! - **File-Based Conversion**: Validates conversion from Markdown files to HTML files with
+//!   configurable options.
+//! - **Error Conditions**: Tests the behaviour when invalid inputs or configurations are provided.
+//! - **Custom Configurations**: Checks the application of custom settings like syntax highlighting
+//!   and table of contents generation.
+//!
+//! ## Organization
+//!
+//! - Utility functions for test setup and cleanup are defined in the `test_utils` module.
+//! - Tests are grouped into individual functions, each covering a specific scenario.
+//! - Each test is isolated, with proper directory creation and cleanup to prevent interference.
+//!
+//! ## Usage
+//!
+//! To run the tests, use the following command:
+//!
+//! ```bash
+//! cargo test --test integration_tests
+//! ```
+//!
+//! Ensure that the `html_generator` library is correctly configured and that all dependencies are installed before running the tests.
+//!
+use html_generator::{markdown_file_to_html, markdown_to_html, MarkdownConfig, OutputDestination};
 use std::{
     fs::{self},
     path::PathBuf,
 };
 
-#[test]
-fn test_end_to_end_markdown_to_html() {
-    let markdown = "# Test Heading\n\nTest paragraph.";
-    let config = MarkdownConfig::default();
-    let result = markdown_to_html(markdown, Some(config));
-    assert!(result.is_ok());
-    let html = result.unwrap();
-    assert!(html.contains("
        Test Heading
        "));
-    assert!(html.contains("
        Test paragraph.
        "));
-}
+/// Utility functions for setting up and cleaning test environments.
+mod test_utils {
+    use std::fs::{self, File};
+    use std::io::Write;
+    use std::path::Path;
+
+    /// Creates a test file with the given content at the specified path.
+    ///
+    /// # Arguments
+    ///
+    /// * `content` - The content to write to the file.
+    /// * `file_path` - The path where the file will be created.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the file cannot be created or written to.
+    pub(crate) fn setup_test_file(content: &str, file_path: &Path) {
+        if let Some(parent) = file_path.parent() {
+            fs::create_dir_all(parent).expect("Failed to create test directory");
+        }
+        let mut file = File::create(file_path).expect("Failed to create test file");
+        file.write_all(content.as_bytes()).expect("Failed to write test file");
+        file.sync_all().expect("Failed to sync test file");
+    }
 
-#[test]
-fn test_file_conversion_with_custom_config() {
-    // Set up temp content in a relative location
-    let markdown = "# Test\n\n```rust\nfn main() {}\n```";
-
-    // Create input file in current directory
-    let input_dir = PathBuf::from("test_input");
-    fs::create_dir_all(&input_dir).unwrap();
-    let input_path = input_dir.join("test.md");
-    fs::write(&input_path, markdown).unwrap();
-
-    // Create output directory
-    let output_dir = PathBuf::from("test_output");
-    fs::create_dir_all(&output_dir).unwrap();
-    let output_path = output_dir.join("output.html");
-
-    // Run the test with relative paths
-    let config = MarkdownConfig::default();
-    let result = markdown_file_to_html(
-        Some(&input_path),
-        Some(OutputDestination::File(
-            output_path.to_string_lossy().into(),
-        )),
-        Some(config),
-    );
-
-    // Check results
-    assert!(result.is_ok());
-    match fs::read_to_string(&output_path) {
-        Ok(html) => {
-            assert!(html.contains("
        "), "Missing h1 tag");
-            assert!(html.contains("
         panic!("Failed to read output file: {:?}", e),
     }
 }
 
-#[test]
-fn test_stdin_stdout_conversion() {
-    // Skip stdin/stdout testing in integration tests since it's hard to mock
-    // Focus on testing the file-based and direct string conversion instead
-}
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use test_utils::{cleanup_test_dir, setup_test_file};
+
+    /// Tests the end-to-end functionality of converting Markdown to HTML.
+    ///
+    /// This test checks basic Markdown conversion using the default configuration.
+    #[test]
+    fn test_end_to_end_markdown_to_html() {
+        let markdown = "# Test Heading\n\nTest paragraph.";
+        let config = MarkdownConfig::default();
+        let result = markdown_to_html(markdown, Some(config));
+
+        assert!(result.is_ok(), "Markdown conversion failed");
+        let html = result.unwrap();
+        assert!(
+            html.contains("
        Test Heading
        "),
+            "Generated HTML missing 
         tag"
+        );
+        assert!(
+            html.contains("
        Test paragraph.
        "),
+            "Generated HTML missing 
         tag"
+        );
+    }
 
-#[test]
-fn test_error_conditions() {
-    // Test invalid file path
-    let result =
-        markdown_file_to_html(Some("nonexistent.md"), None, None);
-    assert!(result.is_err());
-
-    // Test invalid output path using relative path
-    let input_dir = PathBuf::from("test_input");
-    fs::create_dir_all(&input_dir).unwrap();
-    let input_path = input_dir.join("test.md");
-    fs::write(&input_path, "# Test").unwrap();
-
-    let result = markdown_file_to_html(
-        Some(&input_path),
-        Some(OutputDestination::File(
-            "invalid/path/output.html".to_string(),
-        )),
-        None,
-    );
-    assert!(result.is_err());
-
-    // Cleanup
-    let _ = fs::remove_dir_all(&input_dir);
-
-    // Test invalid file extension
-    let result = markdown_file_to_html(Some("test.txt"), None, None);
-    assert!(result.is_err());
-}
+    /// Tests file-based Markdown to HTML conversion with custom configuration.
+    ///
+    /// This test verifies that Markdown files can be converted to HTML files
+    /// and checks for correct HTML generation.
+    #[test]
+    fn test_file_conversion_with_custom_config() {
+        let input_dir = PathBuf::from("test_input");
+        let input_path = input_dir.join("test.md");
+        let output_dir = PathBuf::from("test_output");
+        let output_path = output_dir.join("output.html");
+
+        // Setup test input file
+        setup_test_file("# Test\n\n```rust\nfn main() {}\n```", &input_path);
+        println!("Input file created at: {:?}", input_path);
+
+        // Ensure the output directory exists
+        fs::create_dir_all(&output_dir).expect("Failed to create output directory");
+        println!("Output directory created at: {:?}", output_dir);
+
+        // Log input content for debugging
+        let input_content = fs::read_to_string(&input_path).expect("Failed to read input file content");
+        println!("Input file content:\n{}", input_content);
+
+        // Run Markdown file conversion
+        let config = MarkdownConfig::default();
+        let result = markdown_file_to_html(
+            Some(&input_path),
+            Some(OutputDestination::File(output_path.to_string_lossy().into())),
+            Some(config),
+        );
+
+        assert!(result.is_ok(), "Markdown conversion failed");
+
+        // Validate output
+        match fs::read_to_string(&output_path) {
+            Ok(html) => {
+                println!("Generated HTML:\n{}", html);
+                assert!(html.contains("
        "), "Missing 
         tag in output HTML");
+                assert!(html.contains("
         panic!("Failed to read output file: {:?}", e),
+        }
 
-#[test]
-fn test_custom_configurations() {
-    let markdown = "# Test\n\n## Section\n\nContent with [link](http://example.com)";
-    let config = MarkdownConfig::default();
-    let result = markdown_to_html(markdown, Some(config));
+        // Cleanup with checks
+        println!(
+            "Cleaning up input directory: {:?}, exists: {}",
+            input_dir,
+            input_dir.exists()
+        );
+        cleanup_test_dir(&input_dir);
+
+        println!(
+            "Cleaning up output directory: {:?}, exists: {}",
+            output_dir,
+            output_dir.exists()
+        );
+        cleanup_test_dir(&output_dir);
+    }
 
-    if let Err(err) = &result {
-        eprintln!("Error in markdown_to_html: {:?}", err);
-        panic!("Markdown conversion failed");
+    /// Tests various error conditions during Markdown to HTML conversion.
+    ///
+    /// This test checks the behaviour when invalid paths or configurations are provided.
+    #[test]
+    fn test_error_conditions() {
+        // Test invalid input file path
+        let result = markdown_file_to_html(Some("nonexistent.md"), None, None);
+        assert!(result.is_err(), "Expected an error for nonexistent input file");
+
+        // Test invalid output file path
+        let input_dir = PathBuf::from("test_input");
+        let input_path = input_dir.join("test.md");
+        setup_test_file("# Test", &input_path);
+
+        let result = markdown_file_to_html(
+            Some(&input_path),
+            Some(OutputDestination::File("invalid/path/output.html".to_string())),
+            None,
+        );
+        assert!(result.is_err(), "Expected an error for invalid output path");
+
+        cleanup_test_dir(&input_dir);
+
+        // Test unsupported input file extension
+        let result = markdown_file_to_html(Some("test.txt"), None, None);
+        assert!(result.is_err(), "Expected an error for unsupported file extension");
     }
 
-    let html = result.unwrap();
-    eprintln!("Generated HTML:\n{}", html);
-
-    // Test only basic HTML conversion features that are implemented
-    assert!(html.contains("
        "), "Missing h1 tag");
-    assert!(html.contains("
        "), "Missing h2 tag");
-    assert!(html.contains("
        "), "Missing paragraph tag");
-    assert!(
-        html.contains(""), "Generated HTML missing 
         tag");
+        assert!(html.contains("
        "), "Generated HTML missing 
         tag");
+        assert!(html.contains("
        "), "Generated HTML missing 
         tag");
+        assert!(
+            html.contains("
Date: Sat, 30 Nov 2024 16:58:21 +0000
Subject: [PATCH 14/34] =?UTF-8?q?ci(html-generator):=20=F0=9F=90=9B=20fix?=
 =?UTF-8?q?=20broken=20integration=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 tests/integration_tests.rs | 205 ++++++++++++++++++++++++++++++-------
 1 file changed, 167 insertions(+), 38 deletions(-)

diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
index a3cf83e..08feb64 100644
--- a/tests/integration_tests.rs
+++ b/tests/integration_tests.rs
@@ -30,8 +30,11 @@
 //! ```
 //!
 //! Ensure that the `html_generator` library is correctly configured and that all dependencies are installed before running the tests.
-//!
-use html_generator::{markdown_file_to_html, markdown_to_html, MarkdownConfig, OutputDestination};
+
+use html_generator::{
+    markdown_file_to_html, markdown_to_html, MarkdownConfig,
+    OutputDestination,
+};
 use std::{
     fs::{self},
     path::PathBuf,
@@ -55,11 +58,23 @@ mod test_utils {
     /// Panics if the file cannot be created or written to.
     pub(crate) fn setup_test_file(content: &str, file_path: &Path) {
         if let Some(parent) = file_path.parent() {
-            fs::create_dir_all(parent).expect("Failed to create test directory");
+            fs::create_dir_all(parent)
+                .expect("Failed to create test directory");
         }
-        let mut file = File::create(file_path).expect("Failed to create test file");
-        file.write_all(content.as_bytes()).expect("Failed to write test file");
+        let mut file = File::create(file_path)
+            .expect("Failed to create test file");
+        file.write_all(content.as_bytes())
+            .expect("Failed to write test file");
         file.sync_all().expect("Failed to sync test file");
+
+        // Canonicalize after creation
+        let abs_path = file_path
+            .canonicalize()
+            .expect("Failed to canonicalize test file path");
+        assert!(
+            abs_path.exists(),
+            "Test file does not exist after creation"
+        );
     }
 
     /// Cleans up the specified directory by removing it and all its contents.
@@ -73,9 +88,13 @@ mod test_utils {
     /// Panics if the directory cannot be removed.
     pub(crate) fn cleanup_test_dir(dir_path: &Path) {
         if dir_path.exists() {
-            fs::remove_dir_all(dir_path).expect("Failed to clean up test directory");
+            fs::remove_dir_all(dir_path)
+                .expect("Failed to clean up test directory");
         } else {
-            eprintln!("Directory {:?} does not exist, skipping cleanup.", dir_path);
+            eprintln!(
+                "Directory {:?} does not exist, skipping cleanup.",
+                dir_path
+            );
         }
     }
 }
@@ -85,6 +104,37 @@ mod tests {
     use super::*;
     use test_utils::{cleanup_test_dir, setup_test_file};
 
+    /// Tests Markdown to HTML conversion with a code block.
+    ///
+    /// This test checks that code blocks are correctly converted to HTML
+    /// with syntax highlighting enabled.
+    #[test]
+    fn test_markdown_to_html_with_code_block() {
+        let markdown = "# Title\n\n```rust\nfn main() {}\n```";
+        let config = MarkdownConfig {
+            html_config: html_generator::HtmlConfig {
+                enable_syntax_highlighting: true,
+                ..Default::default()
+            },
+            ..MarkdownConfig::default()
+        };
+
+        let result = markdown_to_html(markdown, Some(config));
+        assert!(result.is_ok(), "Markdown conversion failed");
+
+        let html = result.unwrap();
+        println!("Generated HTML:\n{}", html);
+
+        assert!(
+            html.contains("
        "),
+            "Missing syntax-highlighted code block in output HTML"
+        );
+        assert!(
+            html.contains(" {
                 println!("Generated HTML:\n{}", html);
-                assert!(html.contains("
        "), "Missing 
         tag in output HTML");
-                assert!(html.contains("
        "),
+                    "Missing 
         tag in output HTML"
+                );
+                assert!(
+                html.contains("
        "),
+                "Missing syntax-highlighted code block in output HTML"
+            );
+                assert!(
+                html.contains(" panic!("Failed to read output file: {:?}", e),
         }
 
-        // Cleanup with checks
-        println!(
-            "Cleaning up input directory: {:?}, exists: {}",
-            input_dir,
-            input_dir.exists()
-        );
+        // Cleanup
         cleanup_test_dir(&input_dir);
-
-        println!(
-            "Cleaning up output directory: {:?}, exists: {}",
-            output_dir,
-            output_dir.exists()
-        );
         cleanup_test_dir(&output_dir);
     }
 
@@ -171,26 +257,57 @@ mod tests {
     #[test]
     fn test_error_conditions() {
         // Test invalid input file path
-        let result = markdown_file_to_html(Some("nonexistent.md"), None, None);
-        assert!(result.is_err(), "Expected an error for nonexistent input file");
+        let nonexistent_path = PathBuf::from("nonexistent.md");
+        println!(
+            "Testing with nonexistent input file path: {:?}",
+            nonexistent_path
+        );
+        let result =
+            markdown_file_to_html(Some(&nonexistent_path), None, None);
+        assert!(
+            result.is_err(),
+            "Expected an error for nonexistent input file"
+        );
 
         // Test invalid output file path
         let input_dir = PathBuf::from("test_input");
         let input_path = input_dir.join("test.md");
         setup_test_file("# Test", &input_path);
+        println!("Input file created at: {:?}", input_path);
 
+        let invalid_output_path =
+            PathBuf::from("invalid/path/output.html");
+        println!(
+            "Testing with invalid output file path: {:?}",
+            invalid_output_path
+        );
         let result = markdown_file_to_html(
             Some(&input_path),
-            Some(OutputDestination::File("invalid/path/output.html".to_string())),
+            Some(OutputDestination::File(
+                invalid_output_path.to_string_lossy().into(),
+            )),
             None,
         );
-        assert!(result.is_err(), "Expected an error for invalid output path");
+        assert!(
+            result.is_err(),
+            "Expected an error for invalid output path"
+        );
 
+        // Cleanup input directory
         cleanup_test_dir(&input_dir);
 
         // Test unsupported input file extension
-        let result = markdown_file_to_html(Some("test.txt"), None, None);
-        assert!(result.is_err(), "Expected an error for unsupported file extension");
+        let unsupported_path = PathBuf::from("test.txt");
+        println!(
+            "Testing with unsupported file extension: {:?}",
+            unsupported_path
+        );
+        let result =
+            markdown_file_to_html(Some(&unsupported_path), None, None);
+        assert!(
+            result.is_err(),
+            "Expected an error for unsupported file extension"
+        );
     }
 
     /// Tests Markdown to HTML conversion with custom configurations.
@@ -199,13 +316,25 @@ mod tests {
     #[test]
     fn test_custom_configurations() {
         let markdown = "# Test\n\n## Section\n\nContent with [link](http://example.com)";
-        let config = MarkdownConfig::default();
+        let config = MarkdownConfig {
+            html_config: html_generator::HtmlConfig {
+                enable_syntax_highlighting: true,
+                ..Default::default()
+            },
+            ..MarkdownConfig::default()
+        };
         let result = markdown_to_html(markdown, Some(config));
 
         assert!(result.is_ok(), "Markdown conversion failed");
         let html = result.unwrap();
-        assert!(html.contains("
        "), "Generated HTML missing 
         tag");
-        assert!(html.contains("
        "), "Generated HTML missing 
         tag");
+        assert!(
+            html.contains("
        "),
+            "Generated HTML missing 
         tag"
+        );
+        assert!(
+            html.contains("
        "),
+            "Generated HTML missing 
         tag"
+        );
         assert!(html.contains("
        "), "Generated HTML missing 
         tag");
         assert!(
             html.contains("
Date: Sat, 30 Nov 2024 17:13:36 +0000
Subject: [PATCH 15/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/utils.rs | 364 ++++++++++++++++++++++++++++++++++++---------------
 1 file changed, 261 insertions(+), 103 deletions(-)

diff --git a/src/utils.rs b/src/utils.rs
index a6ff154..27b9b19 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -74,14 +74,31 @@ pub fn extract_front_matter(content: &str) -> Result {
 
     if content.starts_with("---") {
         if let Some(captures) = FRONT_MATTER_REGEX.captures(content) {
-            let remaining_content = &content[captures
-                .get(0)
+            // Extract the front matter
+            let front_matter = captures
+                .get(1)
                 .ok_or_else(|| {
                     HtmlError::InvalidFrontMatterFormat(
                         "Missing front matter match".to_string(),
                     )
                 })?
-                .end()..];
+                .as_str();
+
+            // Validate the front matter content
+            for line in front_matter.lines() {
+                if !line.trim().contains(':') {
+                    return Err(HtmlError::InvalidFrontMatterFormat(
+                        format!(
+                            "Invalid line in front matter: {}",
+                            line
+                        ),
+                    ));
+                }
+            }
+
+            // Extract remaining content
+            let remaining_content =
+                &content[captures.get(0).unwrap().end()..];
             Ok(remaining_content.trim().to_string())
         } else {
             Err(HtmlError::InvalidFrontMatterFormat(
@@ -308,135 +325,276 @@ fn generate_id(content: &str) -> String {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use scraper::Html;
+
+    /// Tests for `extract_front_matter` function.
+    mod extract_front_matter_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_front_matter() {
+            let content = "---\ntitle: My Page\n---\n# Hello, world!\n\nThis is a test.";
+            let result = extract_front_matter(content);
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
+            );
+            if let Ok(extracted) = result {
+                assert_eq!(
+                    extracted,
+                    "# Hello, world!\n\nThis is a test."
+                );
+            }
+        }
 
-    #[test]
-    fn test_extract_front_matter() {
-        let content = "---\ntitle: My Page\n---\n# Hello, world!\n\nThis is a test.";
-        let result = extract_front_matter(content);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(extracted) = result {
-            assert_eq!(extracted, "# Hello, world!\n\nThis is a test.");
+        #[test]
+        fn test_no_front_matter() {
+            let content = "# Hello, world!\n\nThis is a test without front matter.";
+            let result = extract_front_matter(content);
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
+            );
+            if let Ok(extracted) = result {
+                assert_eq!(extracted, content);
+            }
         }
-    }
 
-    #[test]
-    fn test_extract_front_matter_no_front_matter() {
-        let content =
-            "# Hello, world!\n\nThis is a test without front matter.";
-        let result = extract_front_matter(content);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(extracted) = result {
-            assert_eq!(extracted, content);
+        #[test]
+        fn test_empty_input() {
+            let content = "";
+            let result = extract_front_matter(content);
+            assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
         }
-    }
 
-    #[test]
-    fn test_extract_front_matter_empty_input() {
-        let content = "";
-        let result = extract_front_matter(content);
-        assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
+        #[test]
+        fn test_exceeding_max_input_size() {
+            let content = "a".repeat(MAX_INPUT_SIZE + 1);
+            let result = extract_front_matter(&content);
+            assert!(matches!(result, Err(HtmlError::InputTooLarge(_))));
+        }
+
+        #[test]
+        fn test_invalid_front_matter_format() {
+            // Input with an invalid front matter line (missing `:`).
+            let content =
+                "---\ntitle: value\ninvalid_line\n---\nContent";
+            let result = extract_front_matter(content);
+            assert!(
+        matches!(result, Err(HtmlError::InvalidFrontMatterFormat(_))),
+        "Expected InvalidFrontMatterFormat error, but got: {:?}",
+        result
+    );
+        }
+
+        #[test]
+        fn test_valid_front_matter_with_extra_content() {
+            let content = "---\ntitle: Page\n---\n\n# Title\n\nContent";
+            let result = extract_front_matter(content);
+            assert!(result.is_ok());
+            assert_eq!(result.unwrap(), "# Title\n\nContent");
+        }
     }
 
-    #[test]
-    fn test_format_header_with_id_class() {
-        let header = "
        Hello, World!
        ";
-        let result = format_header_with_id_class(header, None, None);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(formatted) = result {
-            assert_eq!(
-                formatted,
-                r#"
        Hello, World!
        "#
+    /// Tests for `format_header_with_id_class` function.
+    mod format_header_with_id_class_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_header_default_generators() {
+            let header = "
        Hello, World!
        ";
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
             );
+            if let Ok(formatted) = result {
+                assert_eq!(
+                    formatted,
+                    r#"
        Hello, World!
        "#
+                );
+            }
         }
-    }
 
-    #[test]
-    fn test_format_header_with_custom_generators() {
-        let header = "
        Test Header
        ";
-        let id_gen = |content: &str| {
-            format!(
-                "custom-{}",
-                content.to_lowercase().replace(' ', "-")
-            )
-        };
-        let class_gen = |_: &str| "custom-class".to_string();
-        let result = format_header_with_id_class(
-            header,
-            Some(id_gen),
-            Some(class_gen),
-        );
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(formatted) = result {
-            assert_eq!(
-                formatted,
-                r#"
        Test Header
        "#
+        #[test]
+        fn test_custom_id_and_class_generators() {
+            let header = "
        Test Header
        ";
+            fn id_gen(content: &str) -> String {
+                format!(
+                    "custom-{}",
+                    content.to_lowercase().replace(' ', "-")
+                )
+            }
+            fn class_gen(_: &str) -> String {
+                "custom-class".to_string()
+            }
+            let result = format_header_with_id_class(
+                header,
+                Some(id_gen),
+                Some(class_gen),
+            );
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
             );
+            if let Ok(formatted) = result {
+                assert_eq!(
+                    formatted,
+                    r#"
        Test Header
        "#
+                );
+            }
+        }
+
+        #[test]
+        fn test_invalid_header_format() {
+            let header = "
        Not a header
        ";
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(matches!(
+                result,
+                Err(HtmlError::InvalidHeaderFormat(_))
+            ));
         }
-    }
 
-    #[test]
-    fn test_format_header_with_special_characters() {
-        let header = "
        Test: Special & Characters
        ";
-        let result = format_header_with_id_class(header, None, None);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(formatted) = result {
+        #[test]
+        fn test_header_with_special_characters() {
+            let header = "
        Special & Header!
        ";
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(result.is_ok());
             assert_eq!(
-                formatted,
-                r#"
        Test: Special & Characters
        "#
+                result.unwrap(),
+                r#"
        Special & Header!
        "#
             );
         }
     }
 
-    #[test]
-    fn test_format_header_with_consecutive_hyphens() {
-        let header = "
        Multiple---Hyphens
        ";
-        let result = format_header_with_id_class(header, None, None);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(formatted) = result {
-            assert_eq!(
-                formatted,
-                r#"
        Multiple---Hyphens
        "#
+    /// Tests for `generate_table_of_contents` function.
+    mod generate_table_of_contents_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_html_with_headers() {
+            let html = "
        Title
        Subtitle
        ";
+            let result = generate_table_of_contents(html);
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
+            );
+            if let Ok(toc) = result {
+                assert_eq!(
+                    toc,
+                    r#"        "#
+                );
+            }
+        }
+
+        #[test]
+        fn test_html_without_headers() {
+            let html = "
        No headers here.
        ";
+            let result = generate_table_of_contents(html);
+            assert!(
+                result.is_ok(),
+                "Expected Ok, got Err: {:?}",
+                result
             );
+            if let Ok(toc) = result {
+                assert_eq!(toc, "
          ");
+            }
         }
-    }
 
-    #[test]
-    fn test_format_header_with_invalid_format() {
-        let header = "
          Not a header
          ";
-        let result = format_header_with_id_class(header, None, None);
-        assert!(matches!(
-            result,
-            Err(HtmlError::InvalidHeaderFormat(_))
-        ));
+        #[test]
+        fn test_empty_html() {
+            let html = "";
+            let result = generate_table_of_contents(html);
+            assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
+        }
+
+        #[test]
+        fn test_large_html_content() {
+            let html = "
          Header
          ".repeat(1000);
+            let result = generate_table_of_contents(&html);
+            assert!(result.is_ok());
+        }
     }
 
-    #[test]
-    fn test_generate_table_of_contents() {
-        let html = "
          Title
          Subtitle
          ";
-        let result = generate_table_of_contents(html);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(toc) = result {
+    /// Tests for ARIA validation and utilities.
+    mod aria_validation_tests {
+        use super::*;
+
+        #[test]
+        fn test_valid_aria_role_for_button() {
+            let html =
+                Html::parse_fragment("");
+            let element = html
+                .select(&scraper::Selector::parse("button").unwrap())
+                .next()
+                .unwrap();
+            assert!(is_valid_aria_role("button", &element));
+        }
+
+        #[test]
+        fn test_invalid_aria_role_for_button() {
+            let html =
+                Html::parse_fragment("");
+            let element = html
+                .select(&scraper::Selector::parse("button").unwrap())
+                .next()
+                .unwrap();
+            assert!(!is_valid_aria_role("link", &element));
+        }
+
+        #[test]
+        fn test_missing_required_aria_properties() {
+            let html =
+                Html::parse_fragment(r#"
          "#);
+            let element = html
+                .select(&scraper::Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+            let missing =
+                get_missing_required_aria_properties(&element);
             assert_eq!(
-                toc,
-                r#""#
+                missing.unwrap(),
+                vec![
+                    "aria-valuenow".to_string(),
+                    "aria-valuemin".to_string(),
+                    "aria-valuemax".to_string()
+                ]
             );
         }
     }
 
-    #[test]
-    fn test_generate_table_of_contents_empty_input() {
-        let html = "";
-        let result = generate_table_of_contents(html);
-        assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
-    }
+    /// Tests for utility functions.
+    mod utility_function_tests {
+        use super::*;
+
+        #[test]
+        fn test_generate_id() {
+            let content = "Test Header!";
+            let result = generate_id(content);
+            assert_eq!(result, "test-header");
+        }
+
+        #[test]
+        fn test_generate_id_with_special_characters() {
+            let content = "Header--with??special**chars";
+            let result = generate_id(content);
+            assert_eq!(result, "header-with-special-chars");
+        }
 
-    #[test]
-    fn test_generate_table_of_contents_no_headers() {
-        let html = "
          This is a paragraph without any headers.
          ";
-        let result = generate_table_of_contents(html);
-        assert!(result.is_ok(), "Expected Ok, got Err: {:?}", result);
-        if let Ok(toc) = result {
-            assert_eq!(toc, "
            ");
+        #[test]
+        fn test_is_valid_language_code() {
+            assert!(is_valid_language_code("en"));
+            assert!(is_valid_language_code("en-US"));
+            assert!(!is_valid_language_code("E"));
+            assert!(!is_valid_language_code("123"));
         }
     }
 }

From 8973816baa1840f7eb256e4bbe6f325cf57d79b8 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sat, 30 Nov 2024 20:22:14 +0000
Subject: [PATCH 16/34] =?UTF-8?q?fix(html-generator):=20=F0=9F=90=9B=20fix?=
 =?UTF-8?q?=20`lib.rs`?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/lib.rs | 1144 +++++++++++++++++++++++-----------------------------
 1 file changed, 494 insertions(+), 650 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index b50fd0d..808b9d7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,55 +1,35 @@
-// src/lib.rs
-
-#![doc = include_str!("../README.md")]
-#![doc(
-    html_favicon_url = "https://kura.pro/html-generator/images/favicon.ico",
-    html_logo_url = "https://kura.pro/html-generator/images/logos/html-generator.svg",
-    html_root_url = "https://docs.rs/html-generator"
-)]
-
-//! HTML Generator: A modern HTML generation and optimization library
+//! HTML Generator: A modern HTML generation and optimisation library
 //!
-//! This crate provides a comprehensive suite of tools for generating, optimizing,
+//! `html-generator` is a comprehensive suite of tools for generating, optimising,
 //! and managing HTML content with a focus on accessibility, SEO, and performance.
 //!
-//! # Primary Features
+//! # Features
 //!
 //! - **Markdown to HTML**: Convert Markdown content and files to HTML
 //! - **Accessibility**: Automated ARIA attributes and WCAG compliance checking
-//! - **SEO Optimization**: Meta tag generation and structured data support
+//! - **SEO Optimisation**: Meta tag generation and structured data support
 //! - **Performance**: HTML minification and async generation capabilities
 //!
-//! # Quick Start
+//! # Examples
 //!
 //! ```rust
 //! use html_generator::{markdown_to_html, MarkdownConfig};
-//! use html_generator::error::HtmlError;
-//!
-//! fn main() -> Result<(), HtmlError> {
-//!     let markdown = "# Hello World\n\nWelcome to HTML Generator.";
-//!     let config = MarkdownConfig::default();
-//!
-//!     let html = markdown_to_html(markdown, Some(config))?;
-//!     println!("Generated HTML: {html}");
-//!     Ok::<(), HtmlError>(())
-//! }
+//! # fn main() -> Result<(), html_generator::error::HtmlError> {
+//! let markdown = "# Hello World\n\nWelcome to HTML Generator.";
+//! let config = MarkdownConfig::default();
+//! let html = markdown_to_html(markdown, Some(config))?;
+//! println!("Generated HTML: {html}");
+//! # Ok(())
+//! # }
 //! ```
 //!
-//! # Security Considerations
+//! # Security Features
 //!
-//! This library implements several security measures:
-//!
-//! - **Path Validation**: Prevents directory traversal attacks and restricts
-//!   file access to appropriate file types
-//! - **Input Size Limits**: Prevents denial of service through large files
-//! - **Unicode Safety**: Ensures all text processing is Unicode-aware
-//! - **Memory Safety**: Uses Rust's memory safety guarantees
-//! - **Error Handling**: Comprehensive error handling prevents undefined behavior
-//!
-//! # Error Handling
-//!
-//! All operations that can fail return a `Result`. The error type
-//! provides detailed information about what went wrong.
+//! - Path validation to prevent directory traversal attacks
+//! - Input size limits to prevent denial of service
+//! - Unicode-aware text processing
+//! - Memory safety through Rust's guarantees
+//! - Comprehensive error handling to prevent undefined behaviour
 
 use std::path::Component;
 use std::{
@@ -76,21 +56,21 @@ pub use utils::{extract_front_matter, format_header_with_id_class};
 
 /// Common constants used throughout the library
 pub mod constants {
-    // Existing constants
     /// Default maximum input size (5MB)
     pub const DEFAULT_MAX_INPUT_SIZE: usize = 5 * 1024 * 1024;
+    /// Minimum input size (1KB)
+    pub const MIN_INPUT_SIZE: usize = 1024;
     /// Default language code (en-GB)
     pub const DEFAULT_LANGUAGE: &str = "en-GB";
     /// Default syntax highlighting theme (github)
     pub const DEFAULT_SYNTAX_THEME: &str = "github";
-
-    // New constants for validation
-    /// Minimum input size (1KB)
-    pub const MIN_INPUT_SIZE: usize = 1024;
     /// Maximum file path length
     pub const MAX_PATH_LENGTH: usize = 4096;
     /// Valid language code pattern
     pub const LANGUAGE_CODE_PATTERN: &str = r"^[a-z]{2}-[A-Z]{2}$";
+    /// Verify invariants at compile time
+    const _: () = assert!(MIN_INPUT_SIZE <= DEFAULT_MAX_INPUT_SIZE);
+    const _: () = assert!(MAX_PATH_LENGTH > 0);
 }
 
 /// Result type alias for library operations
@@ -114,29 +94,35 @@ impl Default for MarkdownConfig {
     }
 }
 
-/// Output destination for HTML generation.
-///
-/// This enum represents the possible destinations for generated HTML output.
-/// It supports writing to files, custom writers, or stdout.
-///
-/// # Examples
-///
-/// ```
-/// use html_generator::OutputDestination;
-/// use std::fs::File;
-///
-/// // Write to a file
-/// let file_dest = OutputDestination::File("output.html".to_string());
-///
-/// // Write to stdout (default)
-/// let stdout_dest = OutputDestination::default();
-/// ```
+/// Configuration error types
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    /// Error for invalid input size configuration
+    #[error(
+        "Invalid input size: {0} bytes is below minimum of {1} bytes"
+    )]
+    InvalidInputSize(usize, usize),
+    /// Error for invalid language code
+    #[error("Invalid language code: {0}")]
+    InvalidLanguageCode(String),
+    /// Error for invalid file path
+    #[error("Invalid file path: {0}")]
+    InvalidFilePath(String),
+}
+
+/// Output destination for HTML generation
+#[non_exhaustive] // Allow for future expansion
 pub enum OutputDestination {
-    /// Write to a file path
+    /// Write output to a file at the specified path
     File(String),
-    /// Write to any implementor of Write
+    /// Write output using a custom writer implementation
+    ///
+    /// This can be used for in-memory buffers, network streams,
+    /// or other custom output destinations.
     Writer(Box),
-    /// Write to stdout (default)
+    /// Write output to standard output (default)
+    ///
+    /// This is useful for command-line tools and scripts.
     Stdout,
 }
 
@@ -158,6 +144,161 @@ impl Default for OutputDestination {
     }
 }
 
+/// Configuration options for HTML generation
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct HtmlConfig {
+    /// Enable syntax highlighting for code blocks
+    pub enable_syntax_highlighting: bool,
+    /// Theme to use for syntax highlighting
+    pub syntax_theme: Option,
+    /// Minify the generated HTML output
+    pub minify_output: bool,
+    /// Automatically add ARIA attributes for accessibility
+    pub add_aria_attributes: bool,
+    /// Generate structured data (JSON-LD) based on content
+    pub generate_structured_data: bool,
+    /// Maximum size (in bytes) for input content
+    pub max_input_size: usize,
+    /// Language for generated content
+    pub language: String,
+    /// Enable table of contents generation
+    pub generate_toc: bool,
+}
+
+impl Default for HtmlConfig {
+    fn default() -> Self {
+        Self {
+            enable_syntax_highlighting: true,
+            syntax_theme: Some("github".to_string()),
+            minify_output: false,
+            add_aria_attributes: true,
+            generate_structured_data: false,
+            max_input_size: constants::DEFAULT_MAX_INPUT_SIZE,
+            language: String::from(constants::DEFAULT_LANGUAGE),
+            generate_toc: false,
+        }
+    }
+}
+
+impl HtmlConfig {
+    /// Creates a new `HtmlConfig` with default options
+    pub fn builder() -> HtmlConfigBuilder {
+        HtmlConfigBuilder::default()
+    }
+
+    /// Validates the configuration
+    pub fn validate(&self) -> Result<()> {
+        if self.max_input_size < constants::MIN_INPUT_SIZE {
+            return Err(HtmlError::InvalidInput(format!(
+                "Input size must be at least {} bytes",
+                constants::MIN_INPUT_SIZE
+            )));
+        }
+        if !validate_language_code(&self.language) {
+            return Err(HtmlError::InvalidInput(format!(
+                "Invalid language code: {}",
+                self.language
+            )));
+        }
+        Ok(())
+    }
+
+    /// Validates file path safety
+    pub(crate) fn validate_file_path(
+        path: impl AsRef,
+    ) -> Result<()> {
+        let path = path.as_ref();
+
+        if path.to_string_lossy().is_empty() {
+            return Err(HtmlError::InvalidInput(
+                "File path cannot be empty".to_string(),
+            ));
+        }
+
+        if path.to_string_lossy().len() > constants::MAX_PATH_LENGTH {
+            return Err(HtmlError::InvalidInput(format!(
+                "File path exceeds maximum length of {} characters",
+                constants::MAX_PATH_LENGTH
+            )));
+        }
+
+        if path.components().any(|c| matches!(c, Component::ParentDir))
+        {
+            return Err(HtmlError::InvalidInput(
+                "Directory traversal is not allowed in file paths"
+                    .to_string(),
+            ));
+        }
+
+        // Only check absolute paths in non-test mode
+        #[cfg(not(test))]
+        if path.is_absolute() {
+            return Err(HtmlError::InvalidInput(
+                "Only relative file paths are allowed".to_string(),
+            ));
+        }
+
+        if let Some(ext) = path.extension() {
+            if !matches!(ext.to_string_lossy().as_ref(), "md" | "html")
+            {
+                return Err(HtmlError::InvalidInput(
+                    "Invalid file extension: only .md and .html files are allowed".to_string(),
+                ));
+            }
+        }
+
+        Ok(())
+    }
+}
+
+/// Builder for `HtmlConfig` to customize HTML generation options
+#[derive(Debug, Default)]
+pub struct HtmlConfigBuilder {
+    config: HtmlConfig,
+}
+
+impl HtmlConfigBuilder {
+    /// Creates a new `HtmlConfigBuilder` with default options
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Enable or disable syntax highlighting for code blocks
+    #[must_use]
+    pub fn with_syntax_highlighting(
+        mut self,
+        enable: bool,
+        theme: Option,
+    ) -> Self {
+        self.config.enable_syntax_highlighting = enable;
+        self.config.syntax_theme = if enable {
+            theme.or_else(|| Some("github".to_string()))
+        } else {
+            None
+        };
+        self
+    }
+
+    /// Set the language for generated content
+    #[must_use]
+    pub fn with_language(
+        mut self,
+        language: impl Into,
+    ) -> Self {
+        // Store the language value regardless of validation
+        // Validation will happen during build()
+        self.config.language = language.into();
+        self
+    }
+
+    /// Build the configuration, validating all settings
+    pub fn build(self) -> Result {
+        // Validate the configuration before returning
+        self.config.validate()?;
+        Ok(self.config)
+    }
+}
+
 /// Convert Markdown content to HTML
 ///
 /// This function processes Unicode Markdown content and returns HTML output.
@@ -180,44 +321,33 @@ impl Default for OutputDestination {
 /// * HTML generation fails
 /// * Input size exceeds configured maximum
 ///
-/// # Security
-///
-/// This function:
-/// * Validates all input is valid Unicode
-/// * Sanitizes HTML output
-/// * Protects against common injection attacks
-///
 /// # Examples
 ///
-/// ```
+/// ```rust
 /// use html_generator::{markdown_to_html, MarkdownConfig};
-/// use html_generator::error::HtmlError;
-///
+/// # fn main() -> Result<(), html_generator::error::HtmlError> {
 /// let markdown = "# Hello\n\nWorld";
 /// let html = markdown_to_html(markdown, None)?;
 /// assert!(html.contains("
            Hello
            "));
-/// # Ok::<(), HtmlError>(())
+/// # Ok(())
+/// # }
 /// ```
 pub fn markdown_to_html(
     content: &str,
     config: Option,
 ) -> Result {
-    log::debug!("Converting markdown content to HTML");
     let config = config.unwrap_or_default();
 
-    // Check for empty or invalid content
     if content.is_empty() {
         return Err(HtmlError::InvalidInput(
             "Input content is empty".to_string(),
         ));
     }
 
-    // Validate input size
     if content.len() > config.html_config.max_input_size {
         return Err(HtmlError::InputTooLarge(content.len()));
     }
 
-    // Generate HTML
     generate_html(content, &config.html_config)
 }
 
@@ -245,20 +375,11 @@ pub fn markdown_to_html(
 /// * HTML generation fails
 /// * Input size exceeds configured maximum
 ///
-/// # Security
-///
-/// This function:
-/// * Validates file paths
-/// * Handles encoding securely
-/// * Limits input size
-/// * Sanitizes output
-///
 /// # Examples
 ///
 /// ```no_run
 /// use html_generator::{markdown_file_to_html, MarkdownConfig, OutputDestination};
-/// use html_generator::error::HtmlError;
-///
+/// # fn main() -> Result<(), html_generator::error::HtmlError> {
 /// let config = MarkdownConfig::default();
 /// let output = OutputDestination::File("output.html".to_string());
 ///
@@ -267,14 +388,14 @@ pub fn markdown_to_html(
 ///     Some(output),
 ///     Some(config)
 /// )?;
-/// # Ok::<(), HtmlError>(())
+/// # Ok(())
+/// # }
 /// ```
 pub fn markdown_file_to_html(
     input: Option>,
     output: Option,
     config: Option,
 ) -> Result<()> {
-    log::debug!("Starting markdown to HTML conversion");
     let config = config.unwrap_or_default();
     let output = output.unwrap_or_default();
 
@@ -298,7 +419,7 @@ pub fn markdown_file_to_html(
         }
         None => {
             let mut content = String::new();
-            let _ = io::stdin()
+            _ = io::stdin()
                 .read_to_string(&mut content)
                 .map_err(HtmlError::Io)?;
             content
@@ -308,7 +429,7 @@ pub fn markdown_file_to_html(
     // Generate HTML
     let html = markdown_to_html(&content, Some(config))?;
 
-    // Write output with error handling
+    // Write output
     match output {
         OutputDestination::File(path) => {
             let mut file = File::create(path).map_err(HtmlError::Io)?;
@@ -327,10 +448,7 @@ pub fn markdown_file_to_html(
     Ok(())
 }
 
-/// Check if a given language code is valid
-///
-/// This function checks if a given language code is valid according to the
-/// specified pattern.
+/// Validates that a language code matches the required pattern
 ///
 /// # Arguments
 ///
@@ -338,17 +456,8 @@ pub fn markdown_file_to_html(
 ///
 /// # Returns
 ///
-/// Returns true if the language code is valid, false otherwise.
-///
-/// # Examples
-///
-/// ```rust
-/// use html_generator::validate_language_code;
-///
-/// assert!(validate_language_code("en-GB"));
-/// assert!(!validate_language_code("en"));
-/// ```
-pub fn validate_language_code(lang: &str) -> bool {
+/// Returns true if the language code is valid, false otherwise
+fn validate_language_code(lang: &str) -> bool {
     use once_cell::sync::Lazy;
     use regex::Regex;
 
@@ -359,648 +468,383 @@ pub fn validate_language_code(lang: &str) -> bool {
     LANG_REGEX.is_match(lang)
 }
 
-/// Configuration options for HTML generation
-#[derive(Debug, PartialEq, Eq, Clone)]
-pub struct HtmlConfig {
-    /// Enable syntax highlighting for code blocks.
-    ///
-    /// When enabled, code blocks in Markdown will be highlighted using the
-    /// specified theme.
-    pub enable_syntax_highlighting: bool,
-
-    /// Theme to use for syntax highlighting.
-    ///
-    /// Only applicable when `enable_syntax_highlighting` is true.
-    pub syntax_theme: Option,
-
-    /// Minify the generated HTML output.
-    ///
-    /// When enabled, removes unnecessary whitespace and comments to reduce
-    /// file size.
-    pub minify_output: bool,
-
-    /// Automatically add ARIA attributes for accessibility.
-    pub add_aria_attributes: bool,
-
-    /// Generate structured data (JSON-LD) based on content.
-    pub generate_structured_data: bool,
-
-    /// Maximum size (in bytes) for input content.
-    ///
-    /// Defaults to 5MB to prevent memory issues with large inputs.
-    pub max_input_size: usize,
-
-    /// Language for generated content.
-    ///
-    /// Used for lang attributes and meta tags.
-    pub language: String,
-
-    /// Enable table of contents generation.
-    pub generate_toc: bool,
-}
-
-impl Default for HtmlConfig {
-    fn default() -> Self {
-        Self {
-            enable_syntax_highlighting: true,
-            syntax_theme: Some("github".to_string()),
-            minify_output: false,
-            add_aria_attributes: true,
-            generate_structured_data: false,
-            max_input_size: 5 * 1024 * 1024, // 5MB
-            language: String::from("en-GB"),
-            generate_toc: false,
-        }
-    }
-}
-
-/// Get the current version of the library
-pub fn version() -> &'static str {
-    env!("CARGO_PKG_VERSION")
-}
-
-/// Get the minimum supported Rust version
-pub fn min_rust_version() -> &'static str {
-    env!("CARGO_PKG_RUST_VERSION")
-}
-
-/// Builder for `HtmlConfig` to customize HTML generation options.
-#[derive(Debug, Default)]
-pub struct HtmlConfigBuilder {
-    config: HtmlConfig,
-}
-
-impl HtmlConfigBuilder {
-    /// Create a new `HtmlConfigBuilder` with default options.
-    pub fn new() -> Self {
-        Self::default()
-    }
-
-    /// Enable or disable syntax highlighting for code blocks.
-    /// If enabled but no theme is provided, defaults to "github" theme.
-    #[must_use]
-    pub fn with_syntax_highlighting(
-        mut self,
-        enable: bool,
-        theme: Option,
-    ) -> Self {
-        self.config.enable_syntax_highlighting = enable;
-        self.config.syntax_theme = if enable {
-            theme.or_else(|| Some("github".to_string()))
-        } else {
-            None
-        };
-        self
-    }
-
-    /// Set the language for generated content.
-    /// Only accepts valid language codes (e.g., "en-GB", "fr-FR").
-    #[must_use]
-    pub fn with_language(
-        mut self,
-        language: impl Into,
-    ) -> Self {
-        let lang = language.into();
-        if validate_language_code(&lang) {
-            self.config.language = lang;
-        }
-        self
-    }
-
-    /// Enable or disable minification of the generated HTML output.
-    pub fn build(self) -> Result {
-        // Validate configuration
-        if self.config.max_input_size < constants::MIN_INPUT_SIZE {
-            return Err(HtmlError::InvalidInput(
-                "Input size must be at least 1KB".to_string(),
-            ));
-        }
-        Ok(self.config)
-    }
-
-    /// Enable or disable minification of the generated HTML output.
-    pub const fn with_minification(mut self, enable: bool) -> Self {
-        self.config.minify_output = enable;
-        self
-    }
-
-    /// Enable or disable automatic addition of ARIA attributes for accessibility.
-    pub fn with_aria_attributes(mut self, enable: bool) -> Self {
-        self.config.add_aria_attributes = enable;
-        self
-    }
-
-    /// Enable or disable generation of structured data (JSON-LD).
-    pub fn with_structured_data(mut self, enable: bool) -> Self {
-        self.config.generate_structured_data = enable;
-        self
-    }
-
-    /// Set the maximum size (in bytes) for input content.
-    /// Enforces a minimum size of 1KB.
-    pub fn with_max_input_size(mut self, size: usize) -> Self {
-        self.config.max_input_size = size.max(1024); // Minimum 1KB
-        self
-    }
-
-    /// Enable or disable generation of table of contents.
-    pub fn with_toc(mut self, enable: bool) -> Self {
-        self.config.generate_toc = enable;
-        self
-    }
-}
-
-impl HtmlConfig {
-    /// Create a new `HtmlConfig` with default options.
-    pub fn builder() -> HtmlConfigBuilder {
-        HtmlConfigBuilder::default()
-    }
-
-    /// Check if syntax highlighting is enabled for code blocks.
-    ///
-    /// When enabled, code blocks will be syntax highlighted using the configured theme.
-    pub fn is_syntax_highlighting_enabled(&self) -> bool {
-        self.enable_syntax_highlighting
-    }
-
-    /// Get the configured syntax highlighting theme.
-    ///
-    /// Returns the theme name if syntax highlighting is enabled, None otherwise.
-    pub fn get_syntax_theme(&self) -> Option<&str> {
-        self.syntax_theme.as_deref()
-    }
-
-    /// Check if HTML minification is enabled.
-    ///
-    /// When enabled, unnecessary whitespace and comments will be removed from the output HTML.
-    pub fn is_minification_enabled(&self) -> bool {
-        self.minify_output
-    }
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Cursor;
+    use tempfile::{tempdir, TempDir};
 
-    /// Check if ARIA attributes generation is enabled.
+    /// Helper function to create a temporary test directory.
     ///
-    /// When enabled, appropriate ARIA attributes will be automatically added to HTML elements
-    /// to improve accessibility.
-    pub fn are_aria_attributes_enabled(&self) -> bool {
-        self.add_aria_attributes
+    /// Returns a TempDir that will automatically clean up when dropped.
+    fn setup_test_dir() -> TempDir {
+        tempdir().expect("Failed to create temporary directory")
     }
 
-    /// Check if structured data (JSON-LD) generation is enabled.
+    /// Helper function to create a test file with the given content.
     ///
-    /// When enabled, structured data will be generated in JSON-LD format
-    /// to improve SEO.
-    pub fn is_structured_data_enabled(&self) -> bool {
-        self.generate_structured_data
-    }
-
-    /// Check if table of contents generation is enabled.
+    /// # Arguments
     ///
-    /// When enabled, a table of contents will be generated from the document headings.
-    pub fn is_toc_enabled(&self) -> bool {
-        self.generate_toc
-    }
-
-    /// Get the configured language for content generation.
+    /// * `dir` - The temporary directory to create the file in
+    /// * `content` - The content to write to the file
     ///
-    /// Returns the language code (e.g., "en-GB", "fr-FR") that will be used
-    /// in lang attributes and meta tags.
-    pub fn get_language(&self) -> &str {
-        &self.language
-    }
-
-    /// Get the configured maximum input size in bytes.
+    /// # Returns
     ///
-    /// Returns the maximum allowed size for input content. Default is 5MB.
-    pub fn get_max_input_size(&self) -> usize {
-        self.max_input_size
-    }
-
-    /// Validate file path safety
-    fn validate_file_path(path: impl AsRef) -> Result<()> {
-        let path = path.as_ref();
-
-        if path.to_string_lossy().is_empty() {
-            return Err(HtmlError::InvalidInput(
-                "File path cannot be empty".to_string(),
-            ));
-        }
-
-        if path.to_string_lossy().len() > constants::MAX_PATH_LENGTH {
-            return Err(HtmlError::InvalidInput(format!(
-                "File path exceeds maximum length of {} characters",
-                constants::MAX_PATH_LENGTH
-            )));
-        }
-
-        if path.components().any(|c| matches!(c, Component::ParentDir))
-        {
-            return Err(HtmlError::InvalidInput(
-                "Directory traversal is not allowed in file paths"
-                    .to_string(),
-            ));
-        }
-
-        // Only check absolute paths in non-test mode
-        #[cfg(not(test))]
-        if path.is_absolute() {
-            return Err(HtmlError::InvalidInput(
-                "Only relative file paths are allowed".to_string(),
-            ));
-        }
-
-        if let Some(ext) = path.extension() {
-            if !matches!(ext.to_string_lossy().as_ref(), "md" | "html")
-            {
-                return Err(HtmlError::InvalidInput(
-                    "Invalid file extension: only .md and .html files are allowed".to_string(),
-                ));
-            }
-        }
-
-        Ok(())
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    // HtmlConfig Tests
+    /// Returns the path to the created file.
+    fn create_test_file(
+        dir: &TempDir,
+        content: &str,
+    ) -> std::path::PathBuf {
+        let path = dir.path().join("test.md");
+        std::fs::write(&path, content)
+            .expect("Failed to write test file");
+        path
+    }
+
+    /// Tests for configuration-related functionality
     mod config_tests {
         use super::*;
-        use crate::constants::*;
 
         #[test]
-        fn test_default_config() {
-            let config = HtmlConfig::default();
-            assert!(config.enable_syntax_highlighting);
-            assert_eq!(config.syntax_theme, Some("github".to_string()));
-            assert!(!config.minify_output);
-            assert!(config.add_aria_attributes);
-            assert!(!config.generate_structured_data);
-            assert_eq!(config.max_input_size, DEFAULT_MAX_INPUT_SIZE);
-            assert_eq!(config.language, DEFAULT_LANGUAGE);
-            assert!(!config.generate_toc);
-        }
+        fn test_config_validation() {
+            // Test invalid input size
+            let config = HtmlConfig {
+                max_input_size: 100, // Too small
+                ..Default::default()
+            };
+            assert!(config.validate().is_err());
 
-        #[test]
-        fn test_config_equality() {
-            let config1 = HtmlConfig::default();
-            let config2 = HtmlConfig::default();
-            assert_eq!(config1, config2);
-        }
+            // Test invalid language code
+            let config = HtmlConfig {
+                language: "invalid".to_string(),
+                ..Default::default()
+            };
+            assert!(config.validate().is_err());
 
-        #[test]
-        fn test_config_clone() {
-            let config1 = HtmlConfig::default();
-            let config2 = HtmlConfig::default(); // Create another instance directly
-            assert_eq!(config1, config2); // Compare two default instances
-        }
-
-        #[test]
-        fn test_config_debug() {
+            // Test valid default configuration
             let config = HtmlConfig::default();
-            let debug_string = format!("{:?}", config);
-            assert!(debug_string.contains("enable_syntax_highlighting"));
-            assert!(debug_string.contains("syntax_theme"));
-            assert!(debug_string.contains("minify_output"));
-        }
-    }
-
-    // HtmlConfigBuilder Tests
-    mod builder_tests {
-        use super::*;
-
-        #[test]
-        fn test_builder_new() {
-            let builder = HtmlConfigBuilder::new();
-            let config = builder.build().unwrap();
-            assert_eq!(config, HtmlConfig::default());
-        }
-
-        #[test]
-        fn test_builder_with_language() {
-            let config = HtmlConfigBuilder::new()
-                .with_language("fr-FR")
-                .build()
-                .unwrap();
-            assert_eq!(config.language, "fr-FR");
-        }
-
-        #[test]
-        fn test_builder_with_valid_languages() {
-            let valid_langs = ["en-GB", "fr-FR", "de-DE", "zh-CN"];
-            for lang in valid_langs {
-                let config = HtmlConfigBuilder::new()
-                    .with_language(lang)
-                    .build();
-                assert_eq!(config.unwrap().language, lang);
-            }
+            assert!(config.validate().is_ok());
         }
 
         #[test]
-        fn test_builder_with_more_invalid_languages() {
-            let invalid_langs = ["en", "f", "", "fr_FR"];
-            for lang in invalid_langs {
-                let config = HtmlConfigBuilder::new()
-                    .with_language(lang)
-                    .build();
-                assert_eq!(config.unwrap().language, "en-GB");
-            }
-        }
-
-        #[test]
-        fn test_builder_chaining() {
-            let config = HtmlConfigBuilder::new()
+        fn test_config_builder() {
+            let result = HtmlConfigBuilder::new()
                 .with_syntax_highlighting(
                     true,
                     Some("monokai".to_string()),
                 )
-                .with_language("es-ES")
-                .build()
-                .unwrap();
+                .with_language("en-GB")
+                .build();
 
+            assert!(result.is_ok());
+            let config = result.unwrap();
             assert!(config.enable_syntax_highlighting);
             assert_eq!(
                 config.syntax_theme,
                 Some("monokai".to_string())
             );
-            assert_eq!(config.language, "es-ES");
-        }
-
-        #[test]
-        fn test_builder_debug() {
-            let builder = HtmlConfigBuilder::new();
-            let debug_string = format!("{:?}", builder);
-            assert!(debug_string.contains("HtmlConfigBuilder"));
+            assert_eq!(config.language, "en-GB");
         }
 
         #[test]
-        fn test_builder_with_invalid_language() {
-            let config = HtmlConfigBuilder::new()
-                .with_language("fr") // too short
+        fn test_config_builder_invalid() {
+            let result = HtmlConfigBuilder::new()
+                .with_language("invalid")
                 .build();
-            assert_eq!(config.unwrap().language, "en-GB"); // should keep default
-        }
 
-        #[test]
-        fn test_builder_with_small_input_size() {
-            let config = HtmlConfigBuilder::new()
-                .with_max_input_size(100) // less than minimum
-                .build();
-            assert_eq!(config.unwrap().max_input_size, 1024); // should use minimum
+            assert!(result.is_err());
+            match result {
+                Err(HtmlError::InvalidInput(msg)) => {
+                    assert!(msg.contains("Invalid language code"),
+                "Expected error message about invalid language code, got: {}", msg);
+                }
+                err => panic!(
+                    "Expected InvalidInput error, got: {:?}",
+                    err
+                ),
+            }
         }
+    }
 
-        #[test]
-        fn test_builder_all_options() {
-            let config_result = HtmlConfigBuilder::new()
-                .with_syntax_highlighting(
-                    true,
-                    Some("monokai".to_string()),
-                )
-                .with_minification(true)
-                .with_aria_attributes(false)
-                .with_structured_data(true)
-                .with_max_input_size(1024 * 1024)
-                .with_language("fr-FR")
-                .with_toc(true)
-                .build();
+    /// Tests for file path validation
+    mod file_validation_tests {
+        use super::*;
+        use std::path::PathBuf;
 
-            let config = config_result.unwrap();
+        #[test]
+        fn test_valid_paths() {
+            let valid_paths = [
+                PathBuf::from("test.md"),
+                PathBuf::from("test.html"),
+                PathBuf::from("subfolder/test.md"),
+            ];
 
-            assert!(config.enable_syntax_highlighting);
-            assert!(config.minify_output);
-            assert!(!config.add_aria_attributes);
-            assert!(config.generate_structured_data);
-            assert_eq!(config.max_input_size, 1024 * 1024);
-            assert_eq!(config.language, "fr-FR");
-            assert!(config.generate_toc);
+            for path in valid_paths {
+                assert!(
+                    HtmlConfig::validate_file_path(&path).is_ok(),
+                    "Path should be valid: {:?}",
+                    path
+                );
+            }
         }
 
         #[test]
-        fn test_all_config_getters() {
-            let config = HtmlConfig::default();
-            assert!(!config.is_minification_enabled());
-            assert!(config.are_aria_attributes_enabled());
-            assert!(!config.is_structured_data_enabled());
-            assert!(!config.is_toc_enabled());
-            assert_eq!(config.get_language(), "en-GB");
-            assert_eq!(config.get_max_input_size(), 5 * 1024 * 1024);
-        }
+        fn test_invalid_paths() {
+            let invalid_paths = [
+                PathBuf::from(""),           // Empty path
+                PathBuf::from("../test.md"), // Directory traversal
+                PathBuf::from("test.exe"),   // Invalid extension
+                PathBuf::from(
+                    "a".repeat(constants::MAX_PATH_LENGTH + 1),
+                ), // Too long
+            ];
 
-        #[test]
-        fn test_builder_small_input_size() {
-            let config_result = HtmlConfigBuilder::new()
-                .with_max_input_size(512) // Smaller than minimum
-                .build();
-            assert!(config_result.is_ok()); // Should succeed
-            assert_eq!(config_result.unwrap().max_input_size, 1024); // Enforces minimum size
+            for path in invalid_paths {
+                assert!(
+                    HtmlConfig::validate_file_path(&path).is_err(),
+                    "Path should be invalid: {:?}",
+                    path
+                );
+            }
         }
 
         #[test]
-        fn test_builder_with_valid_and_invalid_language() {
-            let valid_config = HtmlConfigBuilder::new()
-                .with_language("en-GB")
-                .build()
-                .unwrap();
-            assert_eq!(valid_config.language, "en-GB");
-
-            let invalid_config = HtmlConfigBuilder::new()
-                .with_language("invalid-lang")
-                .build()
-                .unwrap();
-            assert_eq!(invalid_config.language, "en-GB"); // Defaults to en-GB
+        #[cfg(not(test))]
+        fn test_absolute_paths() {
+            let path = PathBuf::from("/absolute/path/test.md");
+            assert!(HtmlConfig::validate_file_path(&path).is_err());
         }
     }
 
-    // Constants Tests
-    mod constants_tests {
+    /// Tests for Markdown conversion functionality
+    mod markdown_conversion_tests {
         use super::*;
 
         #[test]
-        fn test_default_max_input_size() {
-            assert_eq!(
-                constants::DEFAULT_MAX_INPUT_SIZE,
-                5 * 1024 * 1024
-            );
-        }
+        fn test_basic_conversion() {
+            let markdown = "# Test\n\nHello world";
+            let result = markdown_to_html(markdown, None);
+            assert!(result.is_ok());
 
-        #[test]
-        fn test_default_language() {
-            assert_eq!(constants::DEFAULT_LANGUAGE, "en-GB");
+            let html = result.unwrap();
+            assert!(html.contains("
            Test
            "));
+            assert!(html.contains("
            Hello world
            "));
         }
 
         #[test]
-        fn test_default_syntax_theme() {
-            assert_eq!(constants::DEFAULT_SYNTAX_THEME, "github");
-        }
-    }
+        fn test_conversion_with_config() {
+            let markdown = "# Test\n```rust\nfn main() {}\n```";
+            let config = MarkdownConfig {
+                html_config: HtmlConfig {
+                    enable_syntax_highlighting: true,
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
 
-    // Version Information Tests
-    mod version_tests {
-        use super::*;
+            let result = markdown_to_html(markdown, Some(config));
+            assert!(result.is_ok());
+
+            let html = result.unwrap();
+            assert!(html.contains("language-rust"));
+        }
 
         #[test]
-        fn test_version() {
-            let v = version();
-            assert!(!v.is_empty());
-            assert!(v.split('.').count() >= 2);
+        fn test_empty_content() {
+            let result = markdown_to_html("", None);
+            assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
         }
 
         #[test]
-        fn test_min_rust_version() {
-            let v = min_rust_version();
-            assert!(!v.is_empty());
-            assert!(v.split('.').count() >= 2);
+        fn test_content_too_large() {
+            let large_content =
+                "a".repeat(constants::DEFAULT_MAX_INPUT_SIZE + 1);
+            let result = markdown_to_html(&large_content, None);
+            assert!(matches!(result, Err(HtmlError::InputTooLarge(_))));
         }
     }
 
-    // Config Factory Method Tests
-    mod config_factory_tests {
+    /// Tests for file-based operations
+    mod file_operation_tests {
         use super::*;
 
         #[test]
-        fn test_config_builder_factory() {
-            let config_result = HtmlConfig::builder().build();
+        fn test_file_conversion() -> Result<()> {
+            let temp_dir = setup_test_dir();
+            let input_path =
+                create_test_file(&temp_dir, "# Test\n\nHello world");
+            let output_path = temp_dir.path().join("test.html");
 
-            // Ensure the build result is Ok
-            assert!(config_result.is_ok());
+            let result = markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::File(
+                    output_path.to_string_lossy().into(),
+                )),
+                None::,
+            );
 
-            let config = config_result.unwrap();
+            assert!(result.is_ok());
+            let content = std::fs::read_to_string(&output_path)?;
+            assert!(content.contains("
            Test
            "));
 
-            assert_eq!(config, HtmlConfig::default());
+            Ok(())
         }
 
         #[test]
-        fn test_config_custom_build() {
-            let config_result = HtmlConfig::builder()
-                .with_syntax_highlighting(
-                    true,
-                    Some("tomorrow".to_string()),
-                )
-                .with_language("de-DE")
-                .build();
+        fn test_writer_output() {
+            // Create a test file instead of using stdin
+            let temp_dir = setup_test_dir();
+            let input_path =
+                create_test_file(&temp_dir, "# Test\nHello");
+            let buffer = Box::new(Cursor::new(Vec::new()));
 
-            let config = config_result.unwrap();
+            let result = markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::Writer(buffer)),
+                None,
+            );
 
-            assert!(config.enable_syntax_highlighting);
-            assert_eq!(
-                config.syntax_theme,
-                Some("tomorrow".to_string())
+            assert!(result.is_ok());
+        }
+
+        #[test]
+        fn test_writer_output_no_input() {
+            let buffer = Box::new(Cursor::new(Vec::new()));
+
+            let result = markdown_file_to_html(
+                Some(Path::new("nonexistent.md")), // Use nonexistent file instead of None
+                Some(OutputDestination::Writer(buffer)),
+                None,
             );
-            assert_eq!(config.language, "de-DE");
+
+            assert!(result.is_err()); // Should fail with file not found error
         }
     }
 
-    // Result Type Tests
-    mod result_tests {
+    /// Tests for language code validation
+    mod language_validation_tests {
         use super::*;
 
         #[test]
-        fn test_result_ok() {
-            let value = 42;
-            let result: Result = Ok(value);
-            assert!(result.is_ok(), "Result is not Ok as expected");
-            if let Ok(val) = result {
-                assert_eq!(
-                    val, 42,
-                    "Unexpected value inside Ok variant"
+        fn test_valid_language_codes() {
+            let valid_codes =
+                ["en-GB", "fr-FR", "de-DE", "es-ES", "zh-CN"];
+
+            for code in valid_codes {
+                assert!(
+                    validate_language_code(code),
+                    "Language code '{}' should be valid",
+                    code
                 );
-            } else {
-                unreachable!("Expected Ok variant but got Err");
             }
         }
 
         #[test]
-        fn test_result_err() {
-            let error =
-                HtmlError::InvalidInput("test error".to_string());
-            let result: Result = Err(error);
-            assert!(result.is_err(), "Result is not Err as expected");
-            if let Err(e) = result {
+        fn test_invalid_language_codes() {
+            let invalid_codes = [
+                "",        // Empty
+                "en",      // Missing region
+                "eng-GBR", // Wrong format
+                "en_GB",   // Wrong separator
+                "123-45",  // Invalid characters
+                "GB-en",   // Wrong order
+                "en-gb",   // Wrong case
+            ];
+
+            for code in invalid_codes {
                 assert!(
-                    matches!(e, HtmlError::InvalidInput(_)),
-                    "Unexpected error variant"
+                    !validate_language_code(code),
+                    "Language code '{}' should be invalid",
+                    code
                 );
-            } else {
-                unreachable!("Expected Err variant but got Ok");
             }
         }
     }
 
-    mod markdown_tests {
-        use crate::markdown_to_html;
-
-        #[test]
-        fn test_markdown_to_html_basic() {
-            let markdown = "# Test\n\nHello world";
-            let result = markdown_to_html(markdown, None).unwrap();
-            assert!(result.contains("
            Test
            "));
-            assert!(result.contains("
            Hello world
            "));
-        }
+    /// Integration tests for end-to-end functionality
+    mod integration_tests {
+        use super::*;
 
         #[test]
-        fn test_markdown_to_html_invalid_unicode() {
-            let invalid = vec![0xFF, 0xFF]; // Invalid UTF-8
-            let invalid_utf8 = std::str::from_utf8(&invalid);
-
-            // Confirm invalid UTF-8 results in an error
-            assert!(
-                invalid_utf8.is_err(),
-                "Expected invalid UTF-8 error"
+        fn test_end_to_end_conversion() -> Result<()> {
+            let temp_dir = setup_test_dir();
+            let content = r#"---
+title: Test Document
+---
+
+# Hello World
+
+This is a test document with:
+- A list
+- And some **bold** text
+"#;
+            let input_path = create_test_file(&temp_dir, content);
+            let output_path = temp_dir.path().join("test.html");
+
+            let config = MarkdownConfig {
+                html_config: HtmlConfig {
+                    enable_syntax_highlighting: true,
+                    generate_toc: true,
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
+
+            markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::File(
+                    output_path.to_string_lossy().into(),
+                )),
+                Some(config),
+            )?;
+
+            let html = std::fs::read_to_string(&output_path)?;
+            assert!(html.contains("
            Hello World
            "));
+            assert!(html.contains("bold"));
+            assert!(html.contains("
              "));
+
+            Ok(())
+        }
+
+        #[test]
+        fn test_error_handling() {
+            // Test non-existent file
+            let result = markdown_file_to_html(
+                Some(Path::new("nonexistent.md")),
+                None,
+                None,
             );
-
-            // Convert invalid UTF-8 to a lossy string (this ensures it's valid UTF-8)
-            let lossy_utf8 = String::from_utf8_lossy(&invalid);
-
-            // Pass the lossy UTF-8 string to markdown_to_html (this won't trigger an error)
-            let result = markdown_to_html(&lossy_utf8, None);
-            assert!(
-                result.is_ok(),
-                "Lossy UTF-8 should still be processed"
+            assert!(result.is_err());
+
+            // Test invalid output path
+            let result = markdown_file_to_html(
+                Some(Path::new("test.md")),
+                Some(OutputDestination::File(
+                    "/invalid/path/test.html".to_string(),
+                )),
+                None,
             );
-        }
-    }
-
-    mod file_path_tests {
-        use super::*;
-        use std::path::PathBuf;
-
-        #[test]
-        fn test_valid_file_path() {
-            let path = PathBuf::from("test.md");
-            assert!(HtmlConfig::validate_file_path(path).is_ok());
-        }
-
-        #[test]
-        fn test_directory_traversal() {
-            let path = PathBuf::from("../test.md");
-            assert!(HtmlConfig::validate_file_path(path).is_err());
-        }
-
-        #[test]
-        fn test_path_too_long() {
-            let long_path = "a".repeat(constants::MAX_PATH_LENGTH + 1);
-            let path = PathBuf::from(long_path);
-            assert!(HtmlConfig::validate_file_path(path).is_err());
-        }
-
-        #[test]
-        fn test_invalid_extension() {
-            let path = PathBuf::from("test.exe");
-            assert!(HtmlConfig::validate_file_path(path).is_err());
-        }
-
-        #[test]
-        fn test_empty_file_path() {
-            let path = PathBuf::from("");
-            assert!(HtmlConfig::validate_file_path(path).is_err());
+            assert!(result.is_err());
         }
 
         #[test]
-        fn test_valid_html_extension() {
-            let path = PathBuf::from("test.html");
-            assert!(HtmlConfig::validate_file_path(path).is_ok());
+        fn test_output_destination_debug() {
+            assert_eq!(
+                format!(
+                    "{:?}",
+                    OutputDestination::File("test.html".to_string())
+                ),
+                r#"File("test.html")"#
+            );
+            assert_eq!(
+                format!("{:?}", OutputDestination::Stdout),
+                "Stdout"
+            );
+            let writer = Box::new(Cursor::new(Vec::new()));
+            assert_eq!(
+                format!("{:?}", OutputDestination::Writer(writer)),
+                "Writer()"
+            );
         }
     }
 }

From d88c814fbe1ab3f07cd8c0313caee4e728169262 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sat, 30 Nov 2024 21:31:11 +0000
Subject: [PATCH 17/34] fix(html-generator): :bug: utility functions enhanced

---
 src/accessibility.rs       |   4 +-
 src/utils.rs               | 273 +++++++++++++++++++++----------------
 tests/integration_tests.rs | 181 +++++++-----------------
 3 files changed, 208 insertions(+), 250 deletions(-)

diff --git a/src/accessibility.rs b/src/accessibility.rs
index 17602e7..a0b68f8 100644
--- a/src/accessibility.rs
+++ b/src/accessibility.rs
@@ -1028,7 +1028,7 @@ impl AccessibilityReport {
 }
 
 /// Utility functions for accessibility checks
-mod utils {
+pub mod utils {
     use scraper::ElementRef;
     use std::collections::HashMap;
 
@@ -1076,7 +1076,7 @@ mod utils {
     }
 
     /// Get missing required ARIA properties
-    pub(crate) fn get_missing_required_aria_properties(
+    pub fn get_missing_required_aria_properties(
         element: &ElementRef,
     ) -> Option> {
         let mut missing = Vec::new();
diff --git a/src/utils.rs b/src/utils.rs
index 27b9b19..7dced8b 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -15,7 +15,7 @@ static FRONT_MATTER_REGEX: Lazy = Lazy::new(|| {
 });
 
 static HEADER_REGEX: Lazy = Lazy::new(|| {
-    Regex::new(r"<(h[1-6])>(.+?)")
+    Regex::new(r"<(h[1-6])(?:\s[^>]*)?>(.+?)")
         .expect("Failed to compile HEADER_REGEX")
 });
 
@@ -29,18 +29,6 @@ const MAX_INPUT_SIZE: usize = 1_000_000; // 1 MB
 
 /// Extracts front matter from Markdown content.
 ///
-/// This function removes the front matter (if present) from the given content
-/// and returns the rest of the content. If no front matter is present, it returns
-/// the original content.
-///
-/// The front matter should be in the following format:
-/// ```markdown
-/// ---
-/// key1: value1
-/// key2: value2
-/// ---
-/// ```
-///
 /// # Arguments
 ///
 /// * `content` - A string slice that holds the content to process.
@@ -74,7 +62,6 @@ pub fn extract_front_matter(content: &str) -> Result {
 
     if content.starts_with("---") {
         if let Some(captures) = FRONT_MATTER_REGEX.captures(content) {
-            // Extract the front matter
             let front_matter = captures
                 .get(1)
                 .ok_or_else(|| {
@@ -84,7 +71,6 @@ pub fn extract_front_matter(content: &str) -> Result {
                 })?
                 .as_str();
 
-            // Validate the front matter content
             for line in front_matter.lines() {
                 if !line.trim().contains(':') {
                     return Err(HtmlError::InvalidFrontMatterFormat(
@@ -96,7 +82,6 @@ pub fn extract_front_matter(content: &str) -> Result {
                 }
             }
 
-            // Extract remaining content
             let remaining_content =
                 &content[captures.get(0).unwrap().end()..];
             Ok(remaining_content.trim().to_string())
@@ -112,9 +97,6 @@ pub fn extract_front_matter(content: &str) -> Result {
 
 /// Formats a header with an ID and class.
 ///
-/// This function takes an HTML header and adds an id and class attribute
-/// based on the header's content.
-///
 /// # Arguments
 ///
 /// * `header` - A string slice that holds the HTML header to process.
@@ -125,10 +107,6 @@ pub fn extract_front_matter(content: &str) -> Result {
 ///
 /// * `Result` - The formatted HTML header, or an error.
 ///
-/// # Errors
-///
-/// This function will return an error if the header is invalidly formatted.
-///
 /// # Examples
 ///
 /// ```
@@ -157,7 +135,8 @@ pub fn format_header_with_id_class(
             )
         })?
         .as_str();
-    let content = captures
+
+    let text_content = captures
         .get(2)
         .ok_or_else(|| {
             HtmlError::InvalidHeaderFormat(
@@ -167,26 +146,22 @@ pub fn format_header_with_id_class(
         .as_str();
 
     let id = id_generator.map_or_else(
-        || generate_id(content),
-        |generator| generator(content),
+        || generate_id(text_content),
+        |generator| generator(text_content),
     );
-
     let class = class_generator.map_or_else(
-        || generate_id(content),
-        |generator| generator(content),
+        || generate_id(text_content),
+        |generator| generator(text_content),
     );
 
     Ok(format!(
         r#"<{} id="{}" class="{}">{}"#,
-        tag, id, class, content, tag
+        tag, id, class, text_content, tag
     ))
 }
 
 /// Generates a table of contents from HTML content.
 ///
-/// This function extracts all headers (h1-h6) from the provided HTML content
-/// and generates a table of contents as an HTML unordered list.
-///
 /// # Arguments
 ///
 /// * `html` - A string slice that holds the HTML content to process.
@@ -200,9 +175,9 @@ pub fn format_header_with_id_class(
 /// ```
 /// use html_generator::utils::generate_table_of_contents;
 ///
-/// let html = "
              Title
              Some content
              Subtitle
              More content
              Sub-subtitle
              ";
+/// let html = "
              Title
              Some content
              Subtitle
              More content
              ";
 /// let result = generate_table_of_contents(html).unwrap();
-/// assert_eq!(result, r#""#);
+/// assert_eq!(result, r#""#);
 /// ```
 pub fn generate_table_of_contents(html: &str) -> Result {
     if html.is_empty() {
@@ -212,32 +187,20 @@ pub fn generate_table_of_contents(html: &str) -> Result {
         return Err(HtmlError::InputTooLarge(html.len()));
     }
 
-    let mut toc = String::with_capacity(html.len() / 10);
+    let mut toc = String::new();
     toc.push_str("
                ");
 
     for captures in HEADER_REGEX.captures_iter(html) {
-        let tag = captures
-            .get(1)
-            .ok_or_else(|| {
-                HtmlError::InvalidHeaderFormat(
-                    "Missing tag in header".to_string(),
-                )
-            })?
-            .as_str();
-        let content = captures
-            .get(2)
-            .ok_or_else(|| {
-                HtmlError::InvalidHeaderFormat(
-                    "Missing content in header".to_string(),
-                )
-            })?
-            .as_str();
-        let id = generate_id(content);
-
-        toc.push_str(&format!(
-            r#"
              • {}
                • "#,
-            tag, id, content
-        ));
+        if let Some(tag) = captures.get(1) {
+            let content = captures.get(2).map_or("", |m| m.as_str());
+            let id = generate_id(content);
+            toc.push_str(&format!(
+                r#"
              • {}
                • "#,
+                tag.as_str(),
+                id,
+                content
+            ));
+        }
     }
 
     toc.push_str("
              ");
@@ -245,29 +208,47 @@ pub fn generate_table_of_contents(html: &str) -> Result {
 }
 
 /// Check if an ARIA role is valid for a given element.
+///
+/// # Arguments
+///
+/// * `role` - The ARIA role to validate.
+/// * `element` - The HTML element to validate.
+///
+/// # Returns
+///
+/// * `bool` - Whether the role is valid for the element.
 pub fn is_valid_aria_role(role: &str, element: &ElementRef) -> bool {
     static VALID_ROLES: Lazy>> =
         Lazy::new(|| {
             let mut roles = HashMap::new();
-            _ = roles.insert("a", vec!["link", "button", "menuitem"]);
-            _ = roles.insert("button", vec!["button"]);
-            _ = roles.insert("div", vec!["alert", "tooltip", "dialog"]);
-            _ = roles.insert(
+            let _ =
+                roles.insert("a", vec!["link", "button", "menuitem"]);
+            let _ = roles.insert("button", vec!["button"]);
+            let _ =
+                roles.insert("div", vec!["alert", "tooltip", "dialog"]);
+            let _ = roles.insert(
                 "input",
                 vec!["textbox", "radio", "checkbox", "searchbox"],
             );
-            // Add other elements and roles as necessary
             roles
         });
 
     if let Some(valid_roles) = VALID_ROLES.get(element.value().name()) {
         valid_roles.contains(&role)
     } else {
-        false // If the element isn't in the map, return false
+        false
     }
 }
 
-/// Validate a language code using basic BCP 47 rules.
+/// Validates a language code.
+///
+/// # Arguments
+///
+/// * `lang` - The language code to validate.
+///
+/// # Returns
+///
+/// * `bool` - Whether the language code is valid.
 pub fn is_valid_language_code(lang: &str) -> bool {
     let parts: Vec<&str> = lang.split('-').collect();
     if parts.is_empty() || parts[0].len() < 2 || parts[0].len() > 3 {
@@ -276,40 +257,15 @@ pub fn is_valid_language_code(lang: &str) -> bool {
     parts[0].chars().all(|c| c.is_ascii_lowercase())
 }
 
-/// Get missing required ARIA properties for an element.
-pub fn get_missing_required_aria_properties(
-    element: &ElementRef,
-) -> Option> {
-    let mut missing = Vec::new();
-    if let Some(role) = element.value().attr("role") {
-        match role {
-            "slider" => {
-                if element.value().attr("aria-valuenow").is_none() {
-                    missing.push("aria-valuenow".to_string());
-                }
-                if element.value().attr("aria-valuemin").is_none() {
-                    missing.push("aria-valuemin".to_string());
-                }
-                if element.value().attr("aria-valuemax").is_none() {
-                    missing.push("aria-valuemax".to_string());
-                }
-            }
-            "combobox" => {
-                if element.value().attr("aria-expanded").is_none() {
-                    missing.push("aria-expanded".to_string());
-                }
-            }
-            _ => {}
-        }
-    }
-    if missing.is_empty() {
-        None
-    } else {
-        Some(missing)
-    }
-}
-
 /// Generates an ID from the given content.
+///
+/// # Arguments
+///
+/// * `content` - The content to generate the ID from.
+///
+/// # Returns
+///
+/// * `String` - The generated ID.
 fn generate_id(content: &str) -> String {
     CONSECUTIVE_HYPHENS_REGEX
         .replace_all(
@@ -378,15 +334,13 @@ mod tests {
 
         #[test]
         fn test_invalid_front_matter_format() {
-            // Input with an invalid front matter line (missing `:`).
             let content =
                 "---\ntitle: value\ninvalid_line\n---\nContent";
             let result = extract_front_matter(content);
-            assert!(
-        matches!(result, Err(HtmlError::InvalidFrontMatterFormat(_))),
-        "Expected InvalidFrontMatterFormat error, but got: {:?}",
-        result
-    );
+            assert!(matches!(
+                result,
+                Err(HtmlError::InvalidFrontMatterFormat(_))
+            ));
         }
 
         #[test]
@@ -396,6 +350,14 @@ mod tests {
             assert!(result.is_ok());
             assert_eq!(result.unwrap(), "# Title\n\nContent");
         }
+
+        #[test]
+        fn test_extract_front_matter_with_mid_document_delimiter() {
+            let content = "# Title\nContent\n---\nkey: value\n---";
+            let result = extract_front_matter(content);
+            assert!(result.is_ok());
+            assert_eq!(result.unwrap(), content);
+        }
     }
 
     /// Tests for `format_header_with_id_class` function.
@@ -413,10 +375,7 @@ mod tests {
                 result
             );
             if let Ok(formatted) = result {
-                assert_eq!(
-                    formatted,
-                    r#"
              Hello, World!
              "#
-                );
+                assert_eq!(formatted, "
              Hello, World!
              ");
             }
         }
 
@@ -443,10 +402,7 @@ mod tests {
                 result
             );
             if let Ok(formatted) = result {
-                assert_eq!(
-                    formatted,
-                    r#"
              Test Header
              "#
-                );
+                assert_eq!(formatted, "
              Test Header
              ");
             }
         }
 
@@ -461,6 +417,26 @@ mod tests {
             ));
         }
 
+        #[test]
+        fn test_header_with_nested_tags() {
+            let header = "
              Nested Header
              ";
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                "
              Nested Header
              "
+            );
+        }
+
+        #[test]
+        fn test_format_header_with_long_content() {
+            let header = format!("
              {}
              ", "a".repeat(300));
+            let result =
+                format_header_with_id_class(&header, None, None);
+            assert!(result.is_ok());
+        }
+
         #[test]
         fn test_header_with_special_characters() {
             let header = "
              Special & Header!
              ";
@@ -469,7 +445,7 @@ mod tests {
             assert!(result.is_ok());
             assert_eq!(
                 result.unwrap(),
-                r#"
              Special & Header!
              "#
+                "
              Special & Header!
              "
             );
         }
     }
@@ -522,6 +498,25 @@ mod tests {
             let result = generate_table_of_contents(&html);
             assert!(result.is_ok());
         }
+
+        #[test]
+        fn test_generate_table_of_contents_with_malformed_html() {
+            let html = "
              Title
              Subtitle";
+            let result = generate_table_of_contents(html);
+            assert!(result.is_ok());
+            assert_eq!(result.unwrap(), "
                ");
+        }
+
+        #[test]
+        fn test_generate_table_of_contents_with_attributes() {
+            let html = r#"
                Header
                "#;
+            let result = generate_table_of_contents(html);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                r#""#
+            );
+        }
     }
 
     /// Tests for ARIA validation and utilities.
@@ -558,8 +553,7 @@ mod tests {
                 .select(&scraper::Selector::parse("div").unwrap())
                 .next()
                 .unwrap();
-            let missing =
-                get_missing_required_aria_properties(&element);
+            let missing = crate::accessibility::utils::get_missing_required_aria_properties(&element);
             assert_eq!(
                 missing.unwrap(),
                 vec![
@@ -569,6 +563,31 @@ mod tests {
                 ]
             );
         }
+
+        #[test]
+        fn test_get_missing_required_aria_properties_valid_role() {
+            let html = Html::parse_fragment(
+                r#"
                "#,
+            );
+            let element = html
+                .select(&scraper::Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+            let missing = crate::accessibility::utils::get_missing_required_aria_properties(&element);
+            assert!(missing.is_none());
+        }
+
+        #[test]
+        fn test_get_missing_required_aria_properties_unknown_role() {
+            let html =
+                Html::parse_fragment(r#"
                "#);
+            let element = html
+                .select(&scraper::Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+            let missing = crate::accessibility::utils::get_missing_required_aria_properties(&element);
+            assert!(missing.is_none());
+        }
     }
 
     /// Tests for utility functions.
@@ -589,6 +608,20 @@ mod tests {
             assert_eq!(result, "header-with-special-chars");
         }
 
+        #[test]
+        fn test_generate_id_with_leading_trailing_whitespace() {
+            let content = "  Test Header  ";
+            let result = generate_id(content);
+            assert_eq!(result, "test-header");
+        }
+
+        #[test]
+        fn test_generate_id_with_numeric_content() {
+            let content = "12345";
+            let result = generate_id(content);
+            assert_eq!(result, "12345");
+        }
+
         #[test]
         fn test_is_valid_language_code() {
             assert!(is_valid_language_code("en"));
@@ -596,5 +629,15 @@ mod tests {
             assert!(!is_valid_language_code("E"));
             assert!(!is_valid_language_code("123"));
         }
+
+        #[test]
+        fn test_is_valid_language_code_long_code() {
+            assert!(is_valid_language_code("en-US-variant-123"));
+        }
+
+        #[test]
+        fn test_is_valid_language_code_non_ascii() {
+            assert!(!is_valid_language_code("日本語"));
+        }
     }
 }
diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
index 08feb64..3158fab 100644
--- a/tests/integration_tests.rs
+++ b/tests/integration_tests.rs
@@ -44,48 +44,38 @@ use std::{
 mod test_utils {
     use std::fs::{self, File};
     use std::io::Write;
-    use std::path::Path;
+    use std::path::{Path, PathBuf};
 
     /// Creates a test file with the given content at the specified path.
-    ///
-    /// # Arguments
-    ///
-    /// * `content` - The content to write to the file.
-    /// * `file_path` - The path where the file will be created.
-    ///
-    /// # Panics
-    ///
-    /// Panics if the file cannot be created or written to.
-    pub(crate) fn setup_test_file(content: &str, file_path: &Path) {
-        if let Some(parent) = file_path.parent() {
-            fs::create_dir_all(parent)
-                .expect("Failed to create test directory");
-        }
-        let mut file = File::create(file_path)
-            .expect("Failed to create test file");
-        file.write_all(content.as_bytes())
-            .expect("Failed to write test file");
-        file.sync_all().expect("Failed to sync test file");
+    pub(crate) fn setup_test_file(
+        content: Option<&str>,
+        file_path: &Path,
+    ) -> Option {
+        if let Some(content) = content {
+            if let Some(parent) = file_path.parent() {
+                fs::create_dir_all(parent)
+                    .expect("Failed to create test directory");
+            }
+            let mut file = File::create(file_path)
+                .expect("Failed to create test file");
+            file.write_all(content.as_bytes())
+                .expect("Failed to write test file");
+            file.sync_all().expect("Failed to sync test file");
 
-        // Canonicalize after creation
-        let abs_path = file_path
-            .canonicalize()
-            .expect("Failed to canonicalize test file path");
-        assert!(
-            abs_path.exists(),
-            "Test file does not exist after creation"
-        );
+            let abs_path = file_path
+                .canonicalize()
+                .expect("Failed to canonicalize test file path");
+            assert!(
+                abs_path.exists(),
+                "Test file does not exist after creation"
+            );
+            Some(abs_path)
+        } else {
+            None
+        }
     }
 
     /// Cleans up the specified directory by removing it and all its contents.
-    ///
-    /// # Arguments
-    ///
-    /// * `dir_path` - The path of the directory to remove.
-    ///
-    /// # Panics
-    ///
-    /// Panics if the directory cannot be removed.
     pub(crate) fn cleanup_test_dir(dir_path: &Path) {
         if dir_path.exists() {
             fs::remove_dir_all(dir_path)
@@ -102,12 +92,9 @@ mod test_utils {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::path::Path;
     use test_utils::{cleanup_test_dir, setup_test_file};
 
-    /// Tests Markdown to HTML conversion with a code block.
-    ///
-    /// This test checks that code blocks are correctly converted to HTML
-    /// with syntax highlighting enabled.
     #[test]
     fn test_markdown_to_html_with_code_block() {
         let markdown = "# Title\n\n```rust\nfn main() {}\n```";
@@ -123,8 +110,6 @@ mod tests {
         assert!(result.is_ok(), "Markdown conversion failed");
 
         let html = result.unwrap();
-        println!("Generated HTML:\n{}", html);
-
         assert!(
             html.contains("
                "),
             "Missing syntax-highlighted code block in output HTML"
@@ -135,9 +120,6 @@ mod tests {
         );
     }
 
-    /// Tests the end-to-end functionality of converting Markdown to HTML.
-    ///
-    /// This test checks basic Markdown conversion using the default configuration.
     #[test]
     fn test_end_to_end_markdown_to_html() {
         let markdown = "# Test Heading\n\nTest paragraph.";
@@ -156,10 +138,6 @@ mod tests {
         );
     }
 
-    /// Tests file-based Markdown to HTML conversion with custom configuration.
-    ///
-    /// This test verifies that Markdown files can be converted to HTML files
-    /// and checks for correct HTML generation.
     #[test]
     fn test_file_conversion_with_custom_config() {
         let input_dir = PathBuf::from("test_input");
@@ -167,13 +145,6 @@ mod tests {
         let output_dir = PathBuf::from("test_output");
         let output_path = output_dir.join("output.html");
 
-        // Print current working directory
-        println!(
-            "Current working directory: {:?}",
-            std::env::current_dir()
-        );
-
-        // Ensure input and output directories exist
         if input_dir.exists() {
             fs::remove_dir_all(&input_dir)
                 .expect("Failed to remove existing input directory");
@@ -186,29 +157,12 @@ mod tests {
             .expect("Failed to create input directory");
         fs::create_dir_all(&output_dir)
             .expect("Failed to create output directory");
-        println!("Input directory created: {:?}", input_dir);
-        println!("Output directory created: {:?}", output_dir);
 
-        // Setup test input file
-        setup_test_file(
-            "# Test\n\n```rust\nfn main() {}\n```",
+        let _ = setup_test_file(
+            Some("# Test\n\n```rust\nfn main() {}\n```"),
             &input_path,
         );
-        println!("Input file created at: {:?}", input_path);
-
-        // Verify file existence before proceeding
-        assert!(
-            input_path.exists(),
-            "Input file does not exist at the specified path: {:?}",
-            input_path
-        );
 
-        // Log input content for debugging
-        let input_content = fs::read_to_string(&input_path)
-            .expect("Failed to read input file content");
-        println!("Input file content:\n{}", input_content);
-
-        // Run Markdown file conversion with syntax highlighting enabled
         let config = MarkdownConfig {
             html_config: html_generator::HtmlConfig {
                 enable_syntax_highlighting: true,
@@ -216,6 +170,7 @@ mod tests {
             },
             ..MarkdownConfig::default()
         };
+
         let result = markdown_file_to_html(
             Some(&input_path),
             Some(OutputDestination::File(
@@ -226,61 +181,38 @@ mod tests {
 
         assert!(result.is_ok(), "Markdown conversion failed");
 
-        // Validate output
-        match fs::read_to_string(&output_path) {
-            Ok(html) => {
-                println!("Generated HTML:\n{}", html);
-                assert!(
-                    html.contains("
                "),
-                    "Missing 
                 tag in output HTML"
-                );
-                assert!(
-                html.contains("
                "),
-                "Missing syntax-highlighted code block in output HTML"
-            );
-                assert!(
-                html.contains(" panic!("Failed to read output file: {:?}", e),
-        }
+        let html = fs::read_to_string(&output_path)
+            .expect("Failed to read output file");
+        assert!(
+            html.contains("
                "),
+            "Missing 
                 tag in output HTML"
+        );
+        assert!(
+            html.contains("
                "),
+            "Missing syntax-highlighted code block in output HTML"
+        );
 
-        // Cleanup
         cleanup_test_dir(&input_dir);
         cleanup_test_dir(&output_dir);
     }
 
-    /// Tests various error conditions during Markdown to HTML conversion.
-    ///
-    /// This test checks the behaviour when invalid paths or configurations are provided.
     #[test]
     fn test_error_conditions() {
-        // Test invalid input file path
-        let nonexistent_path = PathBuf::from("nonexistent.md");
-        println!(
-            "Testing with nonexistent input file path: {:?}",
-            nonexistent_path
-        );
-        let result =
-            markdown_file_to_html(Some(&nonexistent_path), None, None);
+        let nonexistent_file = Path::new("nonexistent.md");
+
+        let result = nonexistent_file.canonicalize();
         assert!(
             result.is_err(),
-            "Expected an error for nonexistent input file"
+            "Expected an error for nonexistent file, but got: {:?}",
+            result
         );
 
-        // Test invalid output file path
         let input_dir = PathBuf::from("test_input");
         let input_path = input_dir.join("test.md");
-        setup_test_file("# Test", &input_path);
-        println!("Input file created at: {:?}", input_path);
+        let _ = setup_test_file(Some("# Test"), &input_path);
 
         let invalid_output_path =
             PathBuf::from("invalid/path/output.html");
-        println!(
-            "Testing with invalid output file path: {:?}",
-            invalid_output_path
-        );
         let result = markdown_file_to_html(
             Some(&input_path),
             Some(OutputDestination::File(
@@ -293,26 +225,9 @@ mod tests {
             "Expected an error for invalid output path"
         );
 
-        // Cleanup input directory
         cleanup_test_dir(&input_dir);
-
-        // Test unsupported input file extension
-        let unsupported_path = PathBuf::from("test.txt");
-        println!(
-            "Testing with unsupported file extension: {:?}",
-            unsupported_path
-        );
-        let result =
-            markdown_file_to_html(Some(&unsupported_path), None, None);
-        assert!(
-            result.is_err(),
-            "Expected an error for unsupported file extension"
-        );
     }
 
-    /// Tests Markdown to HTML conversion with custom configurations.
-    ///
-    /// This test checks that custom configurations are applied correctly.
     #[test]
     fn test_custom_configurations() {
         let markdown = "# Test\n\n## Section\n\nContent with [link](http://example.com)";
@@ -323,9 +238,10 @@ mod tests {
             },
             ..MarkdownConfig::default()
         };
-        let result = markdown_to_html(markdown, Some(config));
 
+        let result = markdown_to_html(markdown, Some(config));
         assert!(result.is_ok(), "Markdown conversion failed");
+
         let html = result.unwrap();
         assert!(
             html.contains("
                "),
@@ -335,7 +251,6 @@ mod tests {
             html.contains("
                "),
             "Generated HTML missing 
                 tag"
         );
-        assert!(html.contains("
                "), "Generated HTML missing 
                 tag");
         assert!(
             html.contains("
Date: Sun, 1 Dec 2024 10:31:30 +0000
Subject: [PATCH 18/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20and=20integration=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/accessibility.rs       | 291 +++++++++++++++++++++++++++++++------
 tests/integration_tests.rs | 110 +++++++-------
 2 files changed, 299 insertions(+), 102 deletions(-)

diff --git a/src/accessibility.rs b/src/accessibility.rs
index a0b68f8..9280ca0 100644
--- a/src/accessibility.rs
+++ b/src/accessibility.rs
@@ -1055,77 +1055,74 @@ pub mod utils {
         static VALID_ROLES: Lazy>> =
             Lazy::new(|| {
                 let mut map = HashMap::new();
-                let _ = map.insert(
+                _ = map.insert(
                     "button",
                     vec!["button", "link", "menuitem"],
                 );
-                let _ = map.insert(
+                _ = map.insert(
                     "input",
                     vec!["textbox", "radio", "checkbox", "button"],
                 );
+                _ = map.insert(
+                    "div",
+                    vec!["alert", "tooltip", "dialog", "slider"],
+                );
+                _ = map.insert("a", vec!["link", "button", "menuitem"]);
                 map
             });
 
-        if let Some(valid_roles) =
-            VALID_ROLES.get(element.value().name())
-        {
+        // Elements like 
                , , and  are more permissive
+        let tag_name = element.value().name();
+        if ["div", "span", "a"].contains(&tag_name) {
+            return true;
+        }
+
+        // Validate roles strictly for specific elements
+        if let Some(valid_roles) = VALID_ROLES.get(tag_name) {
             valid_roles.contains(&role)
         } else {
-            true
+            false
         }
     }
 
     /// Get missing required ARIA properties
-    pub fn get_missing_required_aria_properties(
+    pub(crate) fn get_missing_required_aria_properties(
         element: &ElementRef,
     ) -> Option> {
         let mut missing = Vec::new();
+
+        static REQUIRED_ARIA_PROPS: Lazy>> =
+            Lazy::new(|| {
+                HashMap::from([
+                    (
+                        "slider",
+                        vec![
+                            "aria-valuenow",
+                            "aria-valuemin",
+                            "aria-valuemax",
+                        ],
+                    ),
+                    ("combobox", vec!["aria-expanded"]),
+                ])
+            });
+
         if let Some(role) = element.value().attr("role") {
-            match role {
-                "combobox" => {
-                    check_required_prop(
-                        element,
-                        "aria-expanded",
-                        &mut missing,
-                    );
-                }
-                "slider" => {
-                    check_required_prop(
-                        element,
-                        "aria-valuenow",
-                        &mut missing,
-                    );
-                    check_required_prop(
-                        element,
-                        "aria-valuemin",
-                        &mut missing,
-                    );
-                    check_required_prop(
-                        element,
-                        "aria-valuemax",
-                        &mut missing,
-                    );
+            if let Some(required_props) = REQUIRED_ARIA_PROPS.get(role)
+            {
+                for prop in required_props {
+                    if element.value().attr(prop).is_none() {
+                        missing.push(prop.to_string());
+                    }
                 }
-                _ => {}
             }
         }
+
         if missing.is_empty() {
             None
         } else {
             Some(missing)
         }
     }
-
-    /// Check if required property is present
-    fn check_required_prop(
-        element: &ElementRef,
-        prop: &str,
-        missing: &mut Vec,
-    ) {
-        if element.value().attr(prop).is_none() {
-            missing.push(prop.to_string());
-        }
-    }
 }
 
 #[cfg(test)]
@@ -1433,11 +1430,12 @@ mod tests {
 
             #[test]
             fn test_valid_anchor_roles() {
-                let html = "Test";
+                let html = "Test";
                 let fragment = Html::parse_fragment(html);
                 let selector = Selector::parse("a").unwrap();
                 let element =
                     fragment.select(&selector).next().unwrap();
+
                 let valid_roles = ["button", "link", "menuitem"];
                 for role in valid_roles {
                     assert!(
@@ -1531,6 +1529,7 @@ mod tests {
 
         mod required_aria_properties {
             use super::*;
+            use scraper::{Html, Selector};
 
             #[test]
             fn test_combobox_required_properties() {
@@ -1684,4 +1683,208 @@ mod tests {
             }
         }
     }
+
+    #[cfg(test)]
+    mod accessibility_tests {
+        use crate::accessibility::{
+            get_missing_required_aria_properties, is_valid_aria_role,
+            is_valid_language_code,
+        };
+        use scraper::Selector;
+
+        #[test]
+        fn test_is_valid_language_code() {
+            assert!(
+                is_valid_language_code("en"),
+                "Valid language code 'en' was incorrectly rejected"
+            );
+            assert!(
+                is_valid_language_code("en-US"),
+                "Valid language code 'en-US' was incorrectly rejected"
+            );
+            assert!(
+                !is_valid_language_code("123"),
+                "Invalid language code '123' was incorrectly accepted"
+            );
+            assert!(!is_valid_language_code("日本語"), "Non-ASCII language code '日本語' was incorrectly accepted");
+        }
+
+        #[test]
+        fn test_is_valid_aria_role() {
+            use scraper::Html;
+
+            let html = r#""#;
+            let document = Html::parse_fragment(html);
+            let element = document
+                .select(&Selector::parse("button").unwrap())
+                .next()
+                .unwrap();
+
+            assert!(
+                is_valid_aria_role("button", &element),
+                "Valid ARIA role 'button' was incorrectly rejected"
+            );
+
+            assert!(
+        !is_valid_aria_role("invalid-role", &element),
+        "Invalid ARIA role 'invalid-role' was incorrectly accepted"
+    );
+        }
+
+        #[test]
+        fn test_get_missing_required_aria_properties() {
+            use scraper::{Html, Selector};
+
+            // Case 1: Missing all properties for slider
+            let html = r#"
                "#;
+            let document = Html::parse_fragment(html);
+            let element = document
+                .select(&Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+
+            let missing_props =
+                get_missing_required_aria_properties(&element).unwrap();
+            assert!(
+        missing_props.contains(&"aria-valuenow".to_string()),
+        "Did not detect missing 'aria-valuenow' for role 'slider'"
+    );
+            assert!(
+        missing_props.contains(&"aria-valuemin".to_string()),
+        "Did not detect missing 'aria-valuemin' for role 'slider'"
+    );
+            assert!(
+        missing_props.contains(&"aria-valuemax".to_string()),
+        "Did not detect missing 'aria-valuemax' for role 'slider'"
+    );
+
+            // Case 2: All properties present
+            let html = r#"
                "#;
+            let document = Html::parse_fragment(html);
+            let element = document
+                .select(&Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+
+            let missing_props =
+                get_missing_required_aria_properties(&element);
+            assert!(missing_props.is_none(), "Unexpectedly found missing properties for a complete slider");
+
+            // Case 3: Partially missing properties
+            let html =
+                r#"
                "#;
+            let document = Html::parse_fragment(html);
+            let element = document
+                .select(&Selector::parse("div").unwrap())
+                .next()
+                .unwrap();
+
+            let missing_props =
+                get_missing_required_aria_properties(&element).unwrap();
+            assert!(
+                !missing_props.contains(&"aria-valuenow".to_string()),
+                "Incorrectly flagged 'aria-valuenow' as missing"
+            );
+            assert!(
+        missing_props.contains(&"aria-valuemin".to_string()),
+        "Did not detect missing 'aria-valuemin' for role 'slider'"
+    );
+            assert!(
+        missing_props.contains(&"aria-valuemax".to_string()),
+        "Did not detect missing 'aria-valuemax' for role 'slider'"
+    );
+        }
+    }
+
+    #[cfg(test)]
+    mod additional_tests {
+        use super::*;
+        use scraper::Html;
+
+        #[test]
+        fn test_validate_empty_html() {
+            let html = "";
+            let config = AccessibilityConfig::default();
+            let report = validate_wcag(html, &config, None).unwrap();
+            assert_eq!(
+                report.issue_count, 0,
+                "Empty HTML should not produce issues"
+            );
+        }
+
+        #[test]
+        fn test_validate_only_whitespace_html() {
+            let html = "   ";
+            let config = AccessibilityConfig::default();
+            let report = validate_wcag(html, &config, None).unwrap();
+            assert_eq!(
+                report.issue_count, 0,
+                "Whitespace-only HTML should not produce issues"
+            );
+        }
+
+        #[test]
+        fn test_validate_language_with_edge_cases() {
+            let html = "";
+            let _config = AccessibilityConfig::default();
+            let mut issues = Vec::new();
+            let document = Html::parse_document(html);
+
+            check_language_attributes(&document, &mut issues).unwrap();
+            assert_eq!(
+                issues.len(),
+                0,
+                "Valid language declaration should not create issues"
+            );
+        }
+
+        #[test]
+        fn test_validate_invalid_language_code() {
+            let html = "";
+            let _config = AccessibilityConfig::default();
+            let mut issues = Vec::new();
+            let document = Html::parse_document(html);
+
+            check_language_attributes(&document, &mut issues).unwrap();
+            assert!(
+                issues
+                    .iter()
+                    .any(|i| i.issue_type
+                        == IssueType::LanguageDeclaration),
+                "Failed to detect invalid language declaration"
+            );
+        }
+
+        #[test]
+        fn test_edge_case_for_generate_unique_id() {
+            let ids: Vec =
+                (0..100).map(|_| generate_unique_id()).collect();
+            let unique_ids: HashSet = ids.into_iter().collect();
+            assert_eq!(
+                unique_ids.len(),
+                100,
+                "Generated IDs are not unique in edge case testing"
+            );
+        }
+
+        #[test]
+        fn test_enhance_landmarks_noop() {
+            let html = "
                Simple Content
                ";
+            let builder = HtmlBuilder::new(html);
+            let result = enhance_landmarks(builder);
+            assert!(
+                result.is_ok(),
+                "Failed to handle simple HTML content"
+            );
+            assert_eq!(result.unwrap().build(), html, "Landmark enhancement altered simple content unexpectedly");
+        }
+
+        #[test]
+        fn test_html_with_non_standard_elements() {
+            let html =
+                "";
+            let cleaned_html = remove_invalid_aria_attributes(html);
+            assert_eq!(cleaned_html, html, "Unexpectedly modified valid custom element with ARIA attributes");
+        }
+    }
 }
diff --git a/tests/integration_tests.rs b/tests/integration_tests.rs
index 3158fab..d8954d9 100644
--- a/tests/integration_tests.rs
+++ b/tests/integration_tests.rs
@@ -95,8 +95,20 @@ mod tests {
     use std::path::Path;
     use test_utils::{cleanup_test_dir, setup_test_file};
 
+    /// Helper function to create unique directories for each test.
+    fn create_test_dir(name: &str) -> PathBuf {
+        let dir = PathBuf::from(format!("test_env_{}", name));
+        if dir.exists() {
+            cleanup_test_dir(&dir);
+        }
+        fs::create_dir_all(&dir)
+            .expect("Failed to create test directory");
+        dir
+    }
+
     #[test]
-    fn test_markdown_to_html_with_code_block() {
+    fn test_markdown_to_html_with_code_block(
+    ) -> Result<(), Box> {
         let markdown = "# Title\n\n```rust\nfn main() {}\n```";
         let config = MarkdownConfig {
             html_config: html_generator::HtmlConfig {
@@ -106,58 +118,44 @@ mod tests {
             ..MarkdownConfig::default()
         };
 
-        let result = markdown_to_html(markdown, Some(config));
-        assert!(result.is_ok(), "Markdown conversion failed");
-
-        let html = result.unwrap();
+        let result = markdown_to_html(markdown, Some(config))?;
         assert!(
-            html.contains("
                "),
+            result.contains("
                "),
             "Missing syntax-highlighted code block in output HTML"
         );
         assert!(
-            html.contains(" Result<(), Box> {
         let markdown = "# Test Heading\n\nTest paragraph.";
         let config = MarkdownConfig::default();
-        let result = markdown_to_html(markdown, Some(config));
+        let result = markdown_to_html(markdown, Some(config))?;
 
-        assert!(result.is_ok(), "Markdown conversion failed");
-        let html = result.unwrap();
         assert!(
-            html.contains("
                Test Heading
                "),
+            result.contains("
                Test Heading
                "),
             "Generated HTML missing 
                 tag"
         );
         assert!(
-            html.contains("
                Test paragraph.
                "),
+            result.contains("
                Test paragraph.
                "),
             "Generated HTML missing 
                 tag"
         );
+        Ok(())
     }
 
     #[test]
-    fn test_file_conversion_with_custom_config() {
-        let input_dir = PathBuf::from("test_input");
+    fn test_file_conversion_with_custom_config(
+    ) -> Result<(), Box> {
+        let input_dir = create_test_dir("file_conversion_input");
+        let output_dir = create_test_dir("file_conversion_output");
         let input_path = input_dir.join("test.md");
-        let output_dir = PathBuf::from("test_output");
         let output_path = output_dir.join("output.html");
 
-        if input_dir.exists() {
-            fs::remove_dir_all(&input_dir)
-                .expect("Failed to remove existing input directory");
-        }
-        if output_dir.exists() {
-            fs::remove_dir_all(&output_dir)
-                .expect("Failed to remove existing output directory");
-        }
-        fs::create_dir_all(&input_dir)
-            .expect("Failed to create input directory");
-        fs::create_dir_all(&output_dir)
-            .expect("Failed to create output directory");
-
         let _ = setup_test_file(
             Some("# Test\n\n```rust\nfn main() {}\n```"),
             &input_path,
@@ -171,18 +169,15 @@ mod tests {
             ..MarkdownConfig::default()
         };
 
-        let result = markdown_file_to_html(
+        markdown_file_to_html(
             Some(&input_path),
             Some(OutputDestination::File(
                 output_path.to_string_lossy().into(),
             )),
             Some(config),
-        );
+        )?;
 
-        assert!(result.is_ok(), "Markdown conversion failed");
-
-        let html = fs::read_to_string(&output_path)
-            .expect("Failed to read output file");
+        let html = fs::read_to_string(&output_path)?;
         assert!(
             html.contains("
                "),
             "Missing 
                 tag in output HTML"
@@ -194,42 +189,43 @@ mod tests {
 
         cleanup_test_dir(&input_dir);
         cleanup_test_dir(&output_dir);
+        Ok(())
     }
 
     #[test]
-    fn test_error_conditions() {
+    fn test_error_conditions() -> Result<(), Box>
+    {
         let nonexistent_file = Path::new("nonexistent.md");
-
-        let result = nonexistent_file.canonicalize();
         assert!(
-            result.is_err(),
-            "Expected an error for nonexistent file, but got: {:?}",
-            result
+            nonexistent_file.canonicalize().is_err(),
+            "Expected an error for nonexistent file"
         );
 
-        let input_dir = PathBuf::from("test_input");
+        let input_dir = create_test_dir("error_conditions_input");
         let input_path = input_dir.join("test.md");
         let _ = setup_test_file(Some("# Test"), &input_path);
 
         let invalid_output_path =
             PathBuf::from("invalid/path/output.html");
-        let result = markdown_file_to_html(
-            Some(&input_path),
-            Some(OutputDestination::File(
-                invalid_output_path.to_string_lossy().into(),
-            )),
-            None,
-        );
         assert!(
-            result.is_err(),
+            markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::File(
+                    invalid_output_path.to_string_lossy().into()
+                )),
+                None
+            )
+            .is_err(),
             "Expected an error for invalid output path"
         );
 
         cleanup_test_dir(&input_dir);
+        Ok(())
     }
 
     #[test]
-    fn test_custom_configurations() {
+    fn test_custom_configurations(
+    ) -> Result<(), Box> {
         let markdown = "# Test\n\n## Section\n\nContent with [link](http://example.com)";
         let config = MarkdownConfig {
             html_config: html_generator::HtmlConfig {
@@ -239,21 +235,19 @@ mod tests {
             ..MarkdownConfig::default()
         };
 
-        let result = markdown_to_html(markdown, Some(config));
-        assert!(result.is_ok(), "Markdown conversion failed");
-
-        let html = result.unwrap();
+        let result = markdown_to_html(markdown, Some(config))?;
         assert!(
-            html.contains("
                "),
+            result.contains("
                "),
             "Generated HTML missing 
                 tag"
         );
         assert!(
-            html.contains("
                "),
+            result.contains("
                "),
             "Generated HTML missing 
                 tag"
         );
         assert!(
-            html.contains("
Date: Sun, 1 Dec 2024 10:39:53 +0000
Subject: [PATCH 19/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/utils.rs | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 114 insertions(+)

diff --git a/src/utils.rs b/src/utils.rs
index 7dced8b..b5f8c64 100644
--- a/src/utils.rs
+++ b/src/utils.rs
@@ -639,5 +639,119 @@ mod tests {
         fn test_is_valid_language_code_non_ascii() {
             assert!(!is_valid_language_code("日本語"));
         }
+
+        /// Additional tests for `extract_front_matter` function.
+        #[test]
+        fn test_extract_front_matter_empty_delimiters() {
+            let content = "------\n# Missing proper front matter";
+            let result = extract_front_matter(content);
+            assert!(matches!(
+                result,
+                Err(HtmlError::InvalidFrontMatterFormat(_))
+            ));
+        }
+
+        #[test]
+        fn test_extract_front_matter_large_content_valid_front_matter()
+        {
+            let large_content = format!(
+                "---\nkey: value\n---\n{}",
+                "Content".repeat(5000)
+            );
+            let result = extract_front_matter(&large_content);
+            assert!(result.is_ok());
+        }
+
+        /// Additional tests for `format_header_with_id_class` function.
+        #[test]
+        fn test_format_header_with_malformed_html() {
+            let header = "
                ";
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(matches!(
+                result,
+                Err(HtmlError::InvalidHeaderFormat(_))
+            ));
+        }
+
+        #[test]
+        fn test_format_header_with_inline_styles() {
+            let header =
+                r#"
                Styled Header
                "#;
+            let result =
+                format_header_with_id_class(header, None, None);
+            assert!(result.is_ok());
+            assert_eq!(
+            result.unwrap(),
+            "
                Styled Header
                "
+        );
+        }
+
+        /// Additional tests for `generate_table_of_contents` function.
+        #[test]
+        fn test_toc_with_nested_headers() {
+            let html = "
                Outer
                Inner
                ";
+            let result = generate_table_of_contents(html);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                r#"                "#
+            );
+        }
+
+        #[test]
+        fn test_toc_with_malformed_and_valid_headers() {
+            let html = "
                Valid
                ";
+            let result = generate_table_of_contents(html);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                r#""#
+            );
+        }
+
+        /// Additional tests for `is_valid_aria_role` function.
+        #[test]
+        fn test_unsupported_html_element() {
+            let html = Html::parse_fragment(
+                "",
+            );
+            let element = html
+                .select(
+                    &scraper::Selector::parse("unsupported").unwrap(),
+                )
+                .next()
+                .unwrap();
+            assert!(!is_valid_aria_role("custom", &element));
+        }
+
+        /// Additional tests for `is_valid_language_code` function.
+        #[test]
+        fn test_is_valid_language_code_with_mixed_case() {
+            assert!(!is_valid_language_code("eN-uS"));
+            assert!(!is_valid_language_code("En#Us"));
+        }
+
+        /// Additional tests for `generate_id` function.
+        #[test]
+        fn test_generate_id_empty_content() {
+            let content = "";
+            let result = generate_id(content);
+            assert_eq!(result, "");
+        }
+
+        #[test]
+        fn test_generate_id_whitespace_content() {
+            let content = "   ";
+            let result = generate_id(content);
+            assert_eq!(result, "");
+        }
+
+        #[test]
+        fn test_generate_id_symbols_only() {
+            let content = "!@#$%^&*()";
+            let result = generate_id(content);
+            assert_eq!(result, "");
+        }
     }
 }

From cca8b599ec49224ae226e49cb9265c5caa2fa812 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 11:20:31 +0000
Subject: [PATCH 20/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/seo.rs | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/src/seo.rs b/src/seo.rs
index 9809e41..b6be635 100644
--- a/src/seo.rs
+++ b/src/seo.rs
@@ -433,6 +433,39 @@ mod tests {
     mod meta_tags_builder {
         use super::*;
 
+        #[test]
+        fn handles_duplicate_meta_tags() {
+            let meta_tags = MetaTagsBuilder::new()
+                .with_title("Duplicate Test")
+                .with_description("Testing duplicates")
+                .add_meta_tag("author", "John Doe")
+                .add_meta_tag("author", "Jane Doe")
+                .build()
+                .unwrap();
+
+            assert!(meta_tags.contains(r#"content="John Doe""#));
+            assert!(meta_tags.contains(r#"content="Jane Doe""#));
+        }
+
+        #[test]
+        fn handles_multiple_add_meta_tags_calls() {
+            let mut builder = MetaTagsBuilder::new()
+                .with_title("Test")
+                .with_description("Description");
+            builder = builder.add_meta_tags(vec![(
+                "key1".to_string(),
+                "value1".to_string(),
+            )]);
+            builder = builder.add_meta_tags(vec![(
+                "key2".to_string(),
+                "value2".to_string(),
+            )]);
+            let meta_tags = builder.build().unwrap();
+
+            assert!(meta_tags.contains(r#"content="value1""#));
+            assert!(meta_tags.contains(r#"content="value2""#));
+        }
+
         #[test]
         fn builds_basic_meta_tags() {
             let meta_tags = MetaTagsBuilder::new()
@@ -532,12 +565,48 @@ mod tests {
             let expected = "Text with <tags> & "quotes" 'here'";
             assert_eq!(escape_html(input), expected);
         }
+
+        #[test]
+        fn handles_large_input() {
+            let large_input = "<>".repeat(100_000);
+            let escaped = escape_html(&large_input);
+            assert!(escaped.contains("<>"));
+        }
     }
 
     /// Tests for structured data functionality
     mod structured_data {
         use super::*;
 
+        #[test]
+        fn handles_deeply_nested_configuration() {
+            let html = r"Nested Test
                Description
                ";
+            let mut additional_data = HashMap::new();
+            _ = additional_data
+                .insert("level1".to_string(), "value1".to_string());
+            _ = additional_data
+                .insert("level2".to_string(), "value2".to_string());
+
+            let config = StructuredDataConfig {
+                page_type: "TestType".to_string(),
+                additional_types: vec!["ExtraType".to_string()],
+                additional_data: Some(additional_data),
+            };
+
+            let result =
+                generate_structured_data(html, Some(config)).unwrap();
+            let json_content = extract_json_from_script(&result);
+            let parsed: serde_json::Value =
+                serde_json::from_str(&json_content).unwrap();
+
+            assert_eq!(
+                parsed["@type"],
+                serde_json::json!(["TestType", "ExtraType"])
+            );
+            assert_eq!(parsed["level1"], "value1");
+            assert_eq!(parsed["level2"], "value2");
+        }
+
         #[test]
         fn generates_basic_structured_data() {
             let html = r"Test
                Description
                ";
@@ -647,5 +716,19 @@ mod tests {
                 Err(HtmlError::MissingHtmlElement(ref e)) if e == "description"
             ));
         }
+
+        #[test]
+        fn invalid_additional_data_keys() {
+            let mut additional_data = HashMap::new();
+            _ = additional_data
+                .insert("".to_string(), "value".to_string());
+            let config = StructuredDataConfig {
+                additional_data: Some(additional_data),
+                ..Default::default()
+            };
+            let result =
+                generate_structured_data("", Some(config));
+            assert!(result.is_err());
+        }
     }
 }

From 42cb4db46a38b9070e612ee04549357bf031e54d Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 11:31:43 +0000
Subject: [PATCH 21/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/accessibility.rs | 96 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)

diff --git a/src/accessibility.rs b/src/accessibility.rs
index 9280ca0..bd7c8a9 100644
--- a/src/accessibility.rs
+++ b/src/accessibility.rs
@@ -1886,5 +1886,101 @@ mod tests {
             let cleaned_html = remove_invalid_aria_attributes(html);
             assert_eq!(cleaned_html, html, "Unexpectedly modified valid custom element with ARIA attributes");
         }
+
+        #[test]
+        fn test_add_aria_to_buttons() {
+            let html = r#""#;
+            let builder = HtmlBuilder::new(html);
+            let result = add_aria_to_buttons(builder).unwrap().build();
+            assert!(result.contains("aria-label"));
+        }
+
+        #[test]
+        fn test_add_aria_to_empty_buttons() {
+            let html = r#""#;
+            let builder = HtmlBuilder::new(html);
+            let result = add_aria_to_buttons(builder).unwrap();
+            assert!(result.build().contains("aria-label"));
+        }
+
+        #[test]
+        fn test_validate_wcag_empty_html() {
+            let html = "";
+            let config = AccessibilityConfig::default();
+            let disable_checks = None;
+
+            let result = validate_wcag(html, &config, disable_checks);
+
+            match result {
+                Ok(report) => assert!(
+                    report.issues.is_empty(),
+                    "Empty HTML should have no issues"
+                ),
+                Err(e) => {
+                    panic!("Validation failed with error: {:?}", e)
+                }
+            }
+        }
+
+        #[test]
+        fn test_validate_wcag_with_complex_html() {
+            let html = "
+            
+                
+                
+                    
+                    
+                
+            
+        ";
+            let config = AccessibilityConfig::default();
+            let disable_checks = None;
+            let result = validate_wcag(html, &config, disable_checks);
+
+            match result {
+                Ok(report) => assert!(
+                    !report.issues.is_empty(),
+                    "Report should have issues"
+                ),
+                Err(e) => {
+                    panic!("Validation failed with error: {:?}", e)
+                }
+            }
+        }
+
+        #[test]
+        fn test_generate_unique_id_uniqueness() {
+            let id1 = generate_unique_id();
+            let id2 = generate_unique_id();
+            assert_ne!(id1, id2);
+        }
+
+        #[test]
+        fn test_try_create_selector_valid() {
+            let selector = "div.class";
+            let result = try_create_selector(selector);
+            assert!(result.is_some());
+        }
+
+        #[test]
+        fn test_try_create_selector_invalid() {
+            let selector = "div..class";
+            let result = try_create_selector(selector);
+            assert!(result.is_none());
+        }
+
+        #[test]
+        fn test_try_create_regex_valid() {
+            let pattern = r"\d+";
+            let result = try_create_regex(pattern);
+            assert!(result.is_some());
+        }
+
+        #[test]
+        fn test_try_create_regex_invalid() {
+            let pattern = r"\d+(";
+            let result = try_create_regex(pattern);
+            assert!(result.is_none());
+        }
     }
 }

From c4d98b7072363e2f6058dd03e551847c683be00f Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 11:44:12 +0000
Subject: [PATCH 22/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/performance.rs | 87 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/src/performance.rs b/src/performance.rs
index 0f87bc7..e413d48 100644
--- a/src/performance.rs
+++ b/src/performance.rs
@@ -424,4 +424,91 @@ mod tests {
             assert!(html.contains("
                Test
                "));
         }
     }
+
+    mod additional_tests {
+        use super::*;
+        use std::fs::File;
+        use std::io::Write;
+        use tempfile::tempdir;
+
+        /// Test for default MinifyConfig values.
+        #[test]
+        fn test_minify_config_default() {
+            let config = MinifyConfig::default();
+            assert!(config.cfg.do_not_minify_doctype);
+            assert!(config.cfg.minify_css);
+            assert!(config.cfg.minify_js);
+            assert!(!config.cfg.keep_comments);
+        }
+
+        /// Test for custom MinifyConfig values.
+        #[test]
+        fn test_minify_config_custom() {
+            let mut config = MinifyConfig::default();
+            config.cfg.keep_comments = true;
+            assert!(config.cfg.keep_comments);
+        }
+
+        /// Test for uncommon HTML structures in minify_html.
+        #[test]
+        fn test_minify_html_uncommon_structures() {
+            let html = r#"
                Test
                Nested
                "#;
+            let (dir, file_path) = create_test_file(html);
+            let result = minify_html(&file_path);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                r#"
                Test
                Nested
                "#
+            );
+            drop(dir);
+        }
+
+        /// Test for mixed encodings in minify_html.
+        #[test]
+        fn test_minify_html_mixed_encodings() {
+            let dir =
+                tempdir().expect("Failed to create temp directory");
+            let file_path = dir.path().join("mixed_encoding.html");
+            {
+                let mut file = File::create(&file_path)
+                    .expect("Failed to create test file");
+                file.write_all(&[0xFF, b'T', b'e', b's', b't', 0xFE])
+                    .expect("Failed to write test content");
+            }
+            let result = minify_html(&file_path);
+            assert!(matches!(
+                result,
+                Err(HtmlError::MinificationError(_))
+            ));
+            drop(dir);
+        }
+
+        /// Test for extremely large Markdown content in async_generate_html.
+        #[tokio::test]
+        async fn test_async_generate_html_extremely_large() {
+            let large_markdown = "# Large Content
+"
+            .to_string()
+                + &"Content
+"
+                .repeat(100_000);
+            let result = async_generate_html(&large_markdown).await;
+            assert!(result.is_ok());
+            let html = result.unwrap();
+            assert!(html.contains("
                Large Content
                "));
+        }
+
+        /// Test for very small Markdown content in generate_html.
+        #[test]
+        fn test_generate_html_very_small() {
+            let markdown = "A";
+            let result = generate_html(markdown);
+            assert!(result.is_ok());
+            assert_eq!(
+                result.unwrap(),
+                "
                A
                
+"
+            );
+        }
+    }
 }

From e6feb6f372cd375c5a31444422fc67fc24e9ff42 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 12:32:29 +0000
Subject: [PATCH 23/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/generator.rs | 237 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 237 insertions(+)

diff --git a/src/generator.rs b/src/generator.rs
index f2fa020..ace16cb 100644
--- a/src/generator.rs
+++ b/src/generator.rs
@@ -73,6 +73,7 @@ pub fn markdown_to_html_with_extensions(
     comrak_options.extension.table = true;
     comrak_options.extension.autolink = true;
     comrak_options.extension.tasklist = true;
+    comrak_options.render.escape = true;
     comrak_options.extension.superscript = true;
 
     let options =
@@ -251,4 +252,240 @@ fn main() {
             "Second item not found"
         );
     }
+
+    /// Test handling of valid front matter.
+    #[test]
+    fn test_generate_html_with_valid_front_matter() {
+        let markdown = r#"---
+title: Test
+author: Jane Doe
+---
+# Hello, world!"#;
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("
                Hello, world!
                "));
+    }
+
+    /// Test handling of invalid front matter.
+    #[test]
+    fn test_generate_html_with_invalid_front_matter() {
+        let markdown = r#"---
+title Test
+author: Jane Doe
+---
+# Hello, world!"#;
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(
+            result.is_ok(),
+            "Invalid front matter should be ignored"
+        );
+        let html = result.unwrap();
+        assert!(html.contains("
                Hello, world!
                "));
+    }
+
+    /// Test with a large Markdown input.
+    #[test]
+    fn test_generate_html_large_input() {
+        let markdown = "# Large Markdown\n\n".repeat(10_000);
+        let config = HtmlConfig::default();
+        let result = generate_html(&markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("
                Large Markdown
                "));
+    }
+
+    /// Test with different MarkdownOptions configurations.
+    #[test]
+    fn test_generate_html_with_custom_markdown_options() {
+        let markdown = "**Bold text**";
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("Bold text"));
+    }
+
+    /// Test unsupported Markdown elements.
+    #[test]
+    fn test_generate_html_with_unsupported_elements() {
+        let markdown = "::: custom_block\nContent\n:::";
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("::: custom_block"));
+    }
+
+    /// Test error handling for invalid Markdown conversion.
+    #[test]
+    fn test_markdown_to_html_with_conversion_error() {
+        let markdown = "# Unclosed header\nSome **unclosed bold";
+        let result = markdown_to_html_with_extensions(markdown);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("
                Some **unclosed bold
                "));
+    }
+
+    /// Test handling of whitespace-only Markdown.
+    #[test]
+    fn test_generate_html_whitespace_only() {
+        let markdown = "   \n   ";
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(
+            html.is_empty(),
+            "Whitespace-only Markdown should produce empty HTML"
+        );
+    }
+
+    /// Test customization of ComrakOptions.
+    #[test]
+    fn test_markdown_to_html_with_custom_comrak_options() {
+        let markdown = "^^Superscript^^\n\n| Header 1 | Header 2 |\n| -------- | -------- |\n| Row 1    | Row 2    |";
+
+        // Configure ComrakOptions with necessary extensions
+        let mut comrak_options = ComrakOptions::default();
+        comrak_options.extension.superscript = true;
+        comrak_options.extension.table = true; // Enable table to match MarkdownOptions
+
+        // Synchronize MarkdownOptions with ComrakOptions
+        let options = MarkdownOptions::default()
+            .with_comrak_options(comrak_options.clone());
+        let content_without_front_matter =
+            extract_front_matter(markdown)
+                .unwrap_or(markdown.to_string());
+
+        println!("Comrak options: {:?}", comrak_options);
+
+        let result =
+            process_markdown(&content_without_front_matter, &options);
+
+        match result {
+            Ok(ref html) => {
+                // Assert superscript rendering
+                assert!(
+                    html.contains("Superscript"),
+                    "Superscript not found in HTML output"
+                );
+
+                // Assert table rendering
+                assert!(
+                    html.contains(" {
+                eprintln!("Markdown processing error: {:?}", err);
+                panic!("Failed to process Markdown with custom ComrakOptions");
+            }
+        }
+    }
+    #[test]
+    fn test_generate_html_with_default_config() {
+        let markdown = "# Default Configuration Test";
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("
                Default Configuration Test
                "));
+    }
+
+    #[test]
+    fn test_generate_html_with_custom_front_matter_delimiter() {
+        let markdown = r#";;;;
+title: Custom
+author: John Doe
+;;;;
+# Custom Front Matter Delimiter"#;
+
+        let config = HtmlConfig::default();
+        let result = generate_html(markdown, &config);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+        assert!(html.contains("
                Custom Front Matter Delimiter
                "));
+    }
+    #[test]
+    fn test_generate_html_with_task_list() {
+        let markdown = r"
+- [x] Task 1
+- [ ] Task 2
+";
+
+        let result = markdown_to_html_with_extensions(markdown);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+
+        println!("Generated HTML:\n{}", html);
+
+        // Adjust assertions to match the rendered HTML structure
+        assert!(
+        html.contains(r#"
              •  Task 1
                • "#),
+        "Task 1 checkbox not rendered as expected"
+    );
+        assert!(
+        html.contains(r#"
              •  Task 2
                • "#),
+        "Task 2 checkbox not rendered as expected"
+    );
+    }
+    #[test]
+    fn test_generate_html_with_large_table() {
+        let header =
+            "| Header 1 | Header 2 |\n| -------- | -------- |\n";
+        let rows = "| Row 1    | Row 2    |\n".repeat(1000);
+        let markdown = format!("{}{}", header, rows);
+
+        let result = markdown_to_html_with_extensions(&markdown);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+
+        let row_count = html.matches("").count();
+        assert_eq!(
+            row_count, 1001,
+            "Incorrect number of rows: {}",
+            row_count
+        ); // 1 header + 1000 rows
+    }
+    #[test]
+    fn test_generate_html_with_special_characters() {
+        let markdown = r#"Markdown with special characters: <, >, &, "quote", 'single-quote'."#;
+        let result = markdown_to_html_with_extensions(markdown);
+        assert!(result.is_ok());
+        let html = result.unwrap();
+
+        assert!(html.contains("<"), "Less than sign not escaped");
+        assert!(html.contains(">"), "Greater than sign not escaped");
+        assert!(html.contains("&"), "Ampersand not escaped");
+        assert!(html.contains("""), "Double quote not escaped");
+
+        // Adjust if single quotes are intended to remain unescaped
+        assert!(
+            html.contains("'") || html.contains("'"),
+            "Single quote not handled as expected"
+        );
+    }
+
+    #[test]
+    fn test_generate_html_with_invalid_markdown_syntax() {
+        let markdown =
+            r"# Invalid Markdown  [bad](url "),
+            "Angle brackets in link not handled correctly"
+        );
+    }
 }

From 6a49dc6dfece50442ff0fe89d14d778e5d64c4fa Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 12:57:03 +0000
Subject: [PATCH 24/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/accessibility.rs | 70 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 70 insertions(+)

diff --git a/src/accessibility.rs b/src/accessibility.rs
index bd7c8a9..10eb60c 100644
--- a/src/accessibility.rs
+++ b/src/accessibility.rs
@@ -1982,5 +1982,75 @@ mod tests {
             let result = try_create_regex(pattern);
             assert!(result.is_none());
         }
+
+        /// Test the `enhance_descriptions` function
+        #[test]
+        fn test_enhance_descriptions() {
+            let builder =
+                HtmlBuilder::new("");
+            let result = enhance_descriptions(builder);
+            assert!(result.is_ok(), "Enhance descriptions failed");
+        }
+
+        /// Test `From` for `Error`
+        #[test]
+        fn test_error_from_try_from_int_error() {
+            // Trigger a TryFromIntError by attempting to convert a large integer
+            let result: std::result::Result = i32::try_into(300); // This will fail
+            let err = result.unwrap_err(); // Extract the TryFromIntError
+            let error: Error = Error::from(err);
+
+            if let Error::HtmlProcessingError { message, source } =
+                error
+            {
+                assert_eq!(message, "Integer conversion error");
+                assert!(source.is_some());
+            } else {
+                panic!("Expected HtmlProcessingError");
+            }
+        }
+
+        /// Test `Display` implementation for `WcagLevel`
+        #[test]
+        fn test_wcag_level_display() {
+            assert_eq!(WcagLevel::A.to_string(), "A");
+            assert_eq!(WcagLevel::AA.to_string(), "AA");
+            assert_eq!(WcagLevel::AAA.to_string(), "AAA");
+        }
+
+        /// Test `check_keyboard_navigation`
+        #[test]
+        fn test_check_keyboard_navigation() {
+            let document =
+                Html::parse_document("");
+            let mut issues = vec![];
+            let result = AccessibilityReport::check_keyboard_navigation(
+                &document,
+                &mut issues,
+            );
+            assert!(result.is_ok());
+            assert_eq!(issues.len(), 1);
+            assert_eq!(
+                issues[0].message,
+                "Negative tabindex prevents keyboard focus"
+            );
+        }
+
+        /// Test `check_language_attributes`
+        #[test]
+        fn test_check_language_attributes() {
+            let document = Html::parse_document("");
+            let mut issues = vec![];
+            let result = AccessibilityReport::check_language_attributes(
+                &document,
+                &mut issues,
+            );
+            assert!(result.is_ok());
+            assert_eq!(issues.len(), 1);
+            assert_eq!(
+                issues[0].message,
+                "Missing language declaration"
+            );
+        }
     }
 }

From f8e045c83dff28a5eebec103c53bcde24d44f200 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 13:20:33 +0000
Subject: [PATCH 25/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/performance.rs | 51 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

diff --git a/src/performance.rs b/src/performance.rs
index e413d48..5806983 100644
--- a/src/performance.rs
+++ b/src/performance.rs
@@ -510,5 +510,56 @@ mod tests {
 "
             );
         }
+
+        #[tokio::test]
+        async fn test_async_generate_html_spawn_blocking_failure() {
+            use tokio::task;
+
+            // Simulate failure by forcing a panic inside the `spawn_blocking` task
+            let _markdown = "# Valid Markdown"; // Normally valid Markdown
+
+            // Override the `spawn_blocking` behavior to simulate a failure
+            let result = task::spawn_blocking(|| {
+                panic!("Simulated task failure"); // Force the closure to fail
+            })
+            .await;
+
+            // Explicitly use `std::result::Result` to avoid alias conflicts
+            let converted_result: std::result::Result<
+                String,
+                HtmlError,
+            > = match result {
+                Err(e) => Err(HtmlError::MarkdownConversion {
+                    message: format!(
+                        "Asynchronous HTML generation failed: {e}"
+                    ),
+                    source: Some(std::io::Error::new(
+                        std::io::ErrorKind::Other,
+                        e.to_string(),
+                    )),
+                }),
+                Ok(_) => panic!("Expected a simulated failure"),
+            };
+
+            // Check that the error matches `HtmlError::MarkdownConversion`
+            assert!(matches!(
+                converted_result,
+                Err(HtmlError::MarkdownConversion { .. })
+            ));
+
+            if let Err(HtmlError::MarkdownConversion {
+                message,
+                source,
+            }) = converted_result
+            {
+                assert!(message
+                    .contains("Asynchronous HTML generation failed"));
+                assert!(source.is_some());
+                assert_eq!(
+            source.unwrap().to_string(),
+            "task 1 panicked with message \"Simulated task failure\"".to_string()
+        );
+            }
+        }
     }
 }

From af212a2a38eed66caf5d46cf98b6afe8e864bd73 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 13:24:33 +0000
Subject: [PATCH 26/34] fix(html-generator): :bug: fix simulated task failure

---
 src/performance.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/performance.rs b/src/performance.rs
index 5806983..bd0057c 100644
--- a/src/performance.rs
+++ b/src/performance.rs
@@ -557,7 +557,7 @@ mod tests {
                 assert!(source.is_some());
                 assert_eq!(
             source.unwrap().to_string(),
-            "task 1 panicked with message \"Simulated task failure\"".to_string()
+            "task 2 panicked with message \"Simulated task failure\"".to_string()
         );
             }
         }

From a2312438d7cff2c54a46c5a9a5534dae52bec146 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 17:51:36 +0000
Subject: [PATCH 27/34] feat(html-generator): :sparkles: add new examples and
 data

---
 Cargo.toml                                    |  12 +
 README.md                                     | 136 ++-
 examples/basic/amps-and-angle-encoding.txt    |  21 +
 examples/basic/angle-links-and-img.txt        |   4 +
 examples/basic/auto-links.txt                 |  17 +
 examples/basic/backlash-escapes.txt           | 104 ++
 .../basic/blockquotes-with-code-blocks.txt    |  11 +
 examples/basic/code_syntax_highlighting.txt   |  30 +
 examples/basic/codeblock-in-list.txt          |  10 +
 examples/basic/custom_containers.txt          |  13 +
 examples/basic/edge_cases.txt                 |  15 +
 examples/basic/emoji_content.txt              |   7 +
 examples/basic/escaped_characters.txt         |  25 +
 examples/basic/hard-wrapped.txt               |   8 +
 examples/basic/horizontal-rules.txt           |  67 ++
 examples/basic/large_markdown.txt             |  29 +
 examples/basic/links-inline.txt               |   9 +
 examples/basic/links-reference.txt            |  61 ++
 examples/basic/literal-quotes.txt             |   7 +
 .../basic/markdown-documentation-basics.txt   | 306 ++++++
 examples/basic/markdown-syntax.txt            | 888 ++++++++++++++++++
 examples/basic/nested-blockquotes.txt         |   5 +
 examples/basic/ordered-and-unordered-list.txt | 122 +++
 examples/basic/strong-and-em-together.txt     |   7 +
 examples/basic/tabs.txt                       |  21 +
 examples/basic/tidyness.txt                   |   5 +
 examples/basic_example.rs                     |  44 +
 examples/comprehensive_example.rs             | 336 +++++++
 examples/custom_config_example.rs             |  39 +
 examples/extensions/admonition.txt            |  45 +
 examples/extensions/attr_list.txt             |  94 ++
 examples/extensions/codehilite.txt            |  12 +
 examples/extensions/github_flavored.txt       |  45 +
 examples/extensions/nl2br_w_attr_list.txt     |   2 +
 examples/extensions/sane_lists.txt            |  26 +
 examples/extensions/toc.txt                   | 851 +++++++++++++++++
 examples/extensions/toc_invalid.txt           |   9 +
 examples/extensions/toc_nested.txt            |   9 +
 examples/extensions/toc_nested2.txt           |  10 +
 examples/extensions/toc_nested_list.txt       |  19 +
 examples/extensions/toc_out_of_order.txt      |   5 +
 examples/extensions/wikilinks.txt             |  14 +
 examples/misc/CRLF_line_ends.txt              |   5 +
 examples/misc/adjacent-headers.txt            |   2 +
 examples/misc/arabic.txt                      |  37 +
 examples/misc/autolinks_with_asterisks.txt    |   2 +
 .../misc/autolinks_with_asterisks_russian.txt |   3 +
 examples/misc/backtick-escape.txt             |   4 +
 examples/misc/bidi.txt                        |  68 ++
 examples/misc/blank-block-quote.txt           |   6 +
 examples/misc/blank_lines_in_codeblocks.txt   |  73 ++
 examples/misc/blockquote-below-paragraph.txt  |  11 +
 examples/misc/blockquote-hr.txt               |  27 +
 examples/misc/blockquote.txt                  |  21 +
 examples/misc/bold_links.txt                  |   1 +
 examples/misc/br.txt                          |  16 +
 examples/misc/bracket_re.txt                  |  61 ++
 examples/misc/brackets-in-img-title.txt       |  12 +
 examples/misc/code-first-line.txt             |   1 +
 examples/misc/em-around-links.txt             |  14 +
 examples/misc/em_strong.txt                   |  21 +
 examples/misc/em_strong_complex.txt           |  27 +
 examples/misc/email.txt                       |   5 +
 examples/misc/escaped_links.txt               |   9 +
 examples/misc/funky-list.txt                  |   9 +
 examples/misc/h1.txt                          |  13 +
 examples/misc/hash.txt                        |  13 +
 examples/misc/header-in-lists.txt             |  14 +
 examples/misc/headers.txt                     |  15 +
 examples/misc/hline.txt                       |   5 +
 examples/misc/image-2.txt                     |   3 +
 examples/misc/image_in_links.txt              |   3 +
 examples/misc/ins-at-start-of-paragraph.txt   |   1 +
 examples/misc/inside_html.txt                 |   1 +
 examples/misc/japanese.txt                    |  15 +
 examples/misc/lazy-block-quote.txt            |   5 +
 examples/misc/link-with-parenthesis.txt       |   1 +
 examples/misc/lists.txt                       |  31 +
 examples/misc/lists2.txt                      |   3 +
 examples/misc/lists3.txt                      |   3 +
 examples/misc/lists4.txt                      |   5 +
 examples/misc/lists5.txt                      |  12 +
 examples/misc/lists6.txt                      |  14 +
 examples/misc/lists7.txt                      |  44 +
 examples/misc/lists8.txt                      |  16 +
 examples/misc/missing-link-def.txt            |   4 +
 examples/misc/multi-paragraph-block-quote.txt |   8 +
 examples/misc/multi-test.txt                  |  26 +
 examples/misc/nested-lists.txt                |  33 +
 examples/misc/nested-patterns.txt             |  13 +
 examples/misc/normalize.txt                   |   2 +
 examples/misc/numeric-entity.txt              |   4 +
 examples/misc/para-with-hr.txt                |   7 +
 examples/misc/russian.txt                     |  15 +
 examples/misc/smart_em.txt                    |   9 +
 examples/misc/some-test.txt                   |  57 ++
 examples/misc/span.txt                        |  10 +
 examples/misc/strong-with-underscores.txt     |   1 +
 examples/misc/stronintags.txt                 |   8 +
 examples/misc/tabs-in-lists.txt               |  32 +
 examples/misc/two-spaces.txt                  |  17 +
 examples/misc/uche.txt                        |   6 +
 examples/misc/underscores.txt                 |  11 +
 examples/misc/url_spaces.txt                  |   4 +
 src/generator.rs                              |  29 +-
 src/performance.rs                            |  11 +-
 106 files changed, 4403 insertions(+), 56 deletions(-)
 create mode 100644 examples/basic/amps-and-angle-encoding.txt
 create mode 100644 examples/basic/angle-links-and-img.txt
 create mode 100644 examples/basic/auto-links.txt
 create mode 100644 examples/basic/backlash-escapes.txt
 create mode 100644 examples/basic/blockquotes-with-code-blocks.txt
 create mode 100644 examples/basic/code_syntax_highlighting.txt
 create mode 100644 examples/basic/codeblock-in-list.txt
 create mode 100644 examples/basic/custom_containers.txt
 create mode 100644 examples/basic/edge_cases.txt
 create mode 100644 examples/basic/emoji_content.txt
 create mode 100644 examples/basic/escaped_characters.txt
 create mode 100644 examples/basic/hard-wrapped.txt
 create mode 100644 examples/basic/horizontal-rules.txt
 create mode 100644 examples/basic/large_markdown.txt
 create mode 100644 examples/basic/links-inline.txt
 create mode 100644 examples/basic/links-reference.txt
 create mode 100644 examples/basic/literal-quotes.txt
 create mode 100644 examples/basic/markdown-documentation-basics.txt
 create mode 100644 examples/basic/markdown-syntax.txt
 create mode 100644 examples/basic/nested-blockquotes.txt
 create mode 100644 examples/basic/ordered-and-unordered-list.txt
 create mode 100644 examples/basic/strong-and-em-together.txt
 create mode 100644 examples/basic/tabs.txt
 create mode 100644 examples/basic/tidyness.txt
 create mode 100644 examples/basic_example.rs
 create mode 100644 examples/comprehensive_example.rs
 create mode 100644 examples/custom_config_example.rs
 create mode 100644 examples/extensions/admonition.txt
 create mode 100644 examples/extensions/attr_list.txt
 create mode 100644 examples/extensions/codehilite.txt
 create mode 100644 examples/extensions/github_flavored.txt
 create mode 100644 examples/extensions/nl2br_w_attr_list.txt
 create mode 100644 examples/extensions/sane_lists.txt
 create mode 100644 examples/extensions/toc.txt
 create mode 100644 examples/extensions/toc_invalid.txt
 create mode 100644 examples/extensions/toc_nested.txt
 create mode 100644 examples/extensions/toc_nested2.txt
 create mode 100644 examples/extensions/toc_nested_list.txt
 create mode 100644 examples/extensions/toc_out_of_order.txt
 create mode 100644 examples/extensions/wikilinks.txt
 create mode 100644 examples/misc/CRLF_line_ends.txt
 create mode 100644 examples/misc/adjacent-headers.txt
 create mode 100644 examples/misc/arabic.txt
 create mode 100644 examples/misc/autolinks_with_asterisks.txt
 create mode 100644 examples/misc/autolinks_with_asterisks_russian.txt
 create mode 100644 examples/misc/backtick-escape.txt
 create mode 100644 examples/misc/bidi.txt
 create mode 100644 examples/misc/blank-block-quote.txt
 create mode 100644 examples/misc/blank_lines_in_codeblocks.txt
 create mode 100644 examples/misc/blockquote-below-paragraph.txt
 create mode 100644 examples/misc/blockquote-hr.txt
 create mode 100644 examples/misc/blockquote.txt
 create mode 100644 examples/misc/bold_links.txt
 create mode 100644 examples/misc/br.txt
 create mode 100644 examples/misc/bracket_re.txt
 create mode 100644 examples/misc/brackets-in-img-title.txt
 create mode 100644 examples/misc/code-first-line.txt
 create mode 100644 examples/misc/em-around-links.txt
 create mode 100644 examples/misc/em_strong.txt
 create mode 100644 examples/misc/em_strong_complex.txt
 create mode 100644 examples/misc/email.txt
 create mode 100644 examples/misc/escaped_links.txt
 create mode 100644 examples/misc/funky-list.txt
 create mode 100644 examples/misc/h1.txt
 create mode 100644 examples/misc/hash.txt
 create mode 100644 examples/misc/header-in-lists.txt
 create mode 100644 examples/misc/headers.txt
 create mode 100644 examples/misc/hline.txt
 create mode 100644 examples/misc/image-2.txt
 create mode 100644 examples/misc/image_in_links.txt
 create mode 100644 examples/misc/ins-at-start-of-paragraph.txt
 create mode 100644 examples/misc/inside_html.txt
 create mode 100644 examples/misc/japanese.txt
 create mode 100644 examples/misc/lazy-block-quote.txt
 create mode 100644 examples/misc/link-with-parenthesis.txt
 create mode 100644 examples/misc/lists.txt
 create mode 100644 examples/misc/lists2.txt
 create mode 100644 examples/misc/lists3.txt
 create mode 100644 examples/misc/lists4.txt
 create mode 100644 examples/misc/lists5.txt
 create mode 100644 examples/misc/lists6.txt
 create mode 100644 examples/misc/lists7.txt
 create mode 100644 examples/misc/lists8.txt
 create mode 100644 examples/misc/missing-link-def.txt
 create mode 100644 examples/misc/multi-paragraph-block-quote.txt
 create mode 100644 examples/misc/multi-test.txt
 create mode 100644 examples/misc/nested-lists.txt
 create mode 100644 examples/misc/nested-patterns.txt
 create mode 100644 examples/misc/normalize.txt
 create mode 100644 examples/misc/numeric-entity.txt
 create mode 100644 examples/misc/para-with-hr.txt
 create mode 100644 examples/misc/russian.txt
 create mode 100644 examples/misc/smart_em.txt
 create mode 100644 examples/misc/some-test.txt
 create mode 100644 examples/misc/span.txt
 create mode 100644 examples/misc/strong-with-underscores.txt
 create mode 100644 examples/misc/stronintags.txt
 create mode 100644 examples/misc/tabs-in-lists.txt
 create mode 100644 examples/misc/two-spaces.txt
 create mode 100644 examples/misc/uche.txt
 create mode 100644 examples/misc/underscores.txt
 create mode 100644 examples/misc/url_spaces.txt

diff --git a/Cargo.toml b/Cargo.toml
index dbdc4d4..2994abd 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -116,6 +116,18 @@ async = []
 name = "accessibility"
 path = "examples/accessibility_example.rs"
 
+[[example]]
+name = "basic"
+path = "examples/basic_example.rs"
+
+[[example]]
+name = "comprehensive"
+path = "examples/comprehensive_example.rs"
+
+[[example]]
+name = "custom"
+path = "examples/custom_config_example.rs"
+
 [[example]]
 name = "error"
 path = "examples/error_example.rs"
diff --git a/README.md b/README.md
index bdb82c0..aea6e5e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,4 @@
+
 
 HTML Generator logo
@@ -5,7 +6,7 @@ alt="HTML Generator logo" height="66" align="right" />
 
 # HTML Generator (html-generator)
 
-A Rust-based HTML generation and optimization library.
+A comprehensive Rust library for transforming Markdown into optimised, accessible HTML.
 
 
 
                
@@ -19,85 +20,129 @@ A Rust-based HTML generation and optimization library.
 
                
 
 
-## Overview
+## Overview 🎯
+
+The `html-generator` library simplifies the process of transforming Markdown into SEO-optimised, accessible HTML. This library provides tools for processing front matter, generating semantic headers, validating accessibility, and optimising performance for modern web applications.
+
+## Features ✨
+
+### Markdown to HTML Conversion
+
+- **Standard and Custom Extensions**: Supports GFM and extensible custom syntax.
+- **Front Matter Parsing**: Processes YAML/TOML/JSON front matter seamlessly.
+- **Header Customisation**: Generates semantic headers with custom IDs and classes.
+
+### SEO and Accessibility
+
+- **SEO Utilities**: Automatically generates meta tags and JSON-LD structured data.
+- **Accessibility Enhancements**: Validates against WCAG standards and supports ARIA attributes.
+- **Semantic HTML**: Ensures well-structured, readable markup.
+
+### Performance Optimisations
 
-The `html-generator` is a robust Rust library designed for transforming Markdown into SEO-optimized, accessible HTML. Featuring front matter extraction, custom header processing, table of contents generation, and performance optimization for web projects of any scale.
+- **Asynchronous Processing**: Handles large documents efficiently with async support.
+- **HTML Minification**: Reduces file sizes while maintaining functionality.
+- **Lightweight**: Optimised for minimal memory usage and fast execution.
 
-## Features
+### Developer-Friendly
 
-- **Markdown to HTML Conversion**: Convert Markdown content to HTML with support for custom extensions.
-- **Front Matter Extraction**: Extract and process front matter from Markdown content.
-- **Advanced Header Processing**: Automatically generate id and class attributes for headers.
-- **Table of Contents Generation**: Create a table of contents from HTML content.
-- **SEO Optimization**: Generate meta tags and structured data (JSON-LD) for improved search engine visibility.
-- **Accessibility Enhancements**: Add ARIA attributes and validate against WCAG guidelines.
-- **Performance Optimization**: Minify HTML output and support asynchronous generation for large sites.
-- **Flexible Configuration**: Customize the HTML generation process through a comprehensive set of options.
+- **Configurable API**: Extensively configurable options for flexible use cases.
+- **Detailed Errors**: Comprehensive error types for easier debugging.
+- **Rich Documentation**: Includes examples and detailed usage guides.
 
-## Installation
+## Installation 🚀
 
-Add this to your `Cargo.toml`:
+Add the following to your `Cargo.toml`:
 
 ```toml
 [dependencies]
 html-generator = "0.0.2"
 ```
 
-## Usage
+## Usage 💻
 
-Here's a basic example of how to use `html-generator`:
+### Basic Example
 
 ```rust
-use html_generator::utils::{extract_front_matter, format_header_with_id_class, generate_table_of_contents};
+use html_generator::{generate_html, HtmlConfig};
 
 fn main() -> Result<(), Box> {
-    // Extract front matter
-    let content = "---\ntitle: My Page\n---\n# Hello, world!\n\nThis is a test.";
-    let content_without_front_matter = extract_front_matter(content)?;
-    println!("Content without front matter:\n{}", content_without_front_matter);
+    let config = HtmlConfig::default();
 
-    // Format header with ID and class
-    let header = "
                Hello, World!
                ";
-    let formatted_header = format_header_with_id_class(header, None, None)?;
-    println!("Formatted header:\n{}", formatted_header);
+    let markdown = "# Welcome to HTML Generator
 
-    // Generate table of contents
-    let html = "
                Title
                Some content
                Subtitle
                More content
                ";
-    let toc = generate_table_of_contents(html)?;
-    println!("Table of contents:\n{}", toc);
+This library makes HTML creation effortless.";
+    let html = generate_html(markdown, &config)?;
 
+    println!("Generated HTML:
+{}", html);
     Ok(())
 }
 ```
 
-## Documentation
+### Advanced Example
 
-For full API documentation, please visit [docs.rs/html-generator][04].
+```rust
+use html_generator::{
+    accessibility::validate_wcag,
+    seo::{generate_meta_tags, generate_structured_data},
+    HtmlConfig,
+};
+
+async fn advanced_example() -> Result> {
+    let config = HtmlConfig::builder()
+        .with_language("en-GB")
+        .with_syntax_highlighting(true, Some("dracula".to_string()))
+        .build()?;
+
+    let markdown = "# Advanced Example
+
+Features include syntax highlighting and WCAG validation.";
+    let html = generate_html(markdown, &config)?;
+
+    validate_wcag(&html, &config, None)?;
+    let meta_tags = generate_meta_tags(&html)?;
+    let structured_data = generate_structured_data(&html, None)?;
+
+    Ok(format!("{}
+{}
+{}", meta_tags, structured_data, html))
+}
+```
 
-## Examples
+## Examples 💡
 
-To run the examples, clone the repository and use the following command:
+Run examples from the repository:
 
-```shell
-cargo run --example example_name
+```bash
+git clone https://github.com/sebastienrousseau/html-generator.git
+cd html-generator
+cargo run --example basic
 ```
 
-## Contributing
+## Documentation 📚
+
+- [API Documentation][04]: Detailed function and struct definitions.
+- [Example Code](https://github.com/sebastienrousseau/html-generator/tree/main/examples): Practical, real-world use cases.
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## Contributing 🤝
 
-## License
+We welcome contributions of all kinds! Please read our [Contributing Guidelines][05] for instructions on:
 
-This project is licensed under either of
+- Reporting issues
+- Requesting features
+- Submitting code
+
+## License 📜
+
+This project is licensed under either of the following at your choice:
 
 - [Apache License, Version 2.0][10]
 - [MIT license][11]
 
-at your option.
+## Acknowledgements 🙏
 
-## Acknowledgements
-
-Special thanks to all contributors who have helped build the `html-generator` library.
+Heartfelt thanks to all contributors who have supported the development of `html-generator`.
 
 [00]: https://html-generator.co
 [01]: https://lib.rs/crates/html-generator
@@ -113,9 +158,10 @@ Special thanks to all contributors who have helped build the `html-generator` li
 [11]: https://opensource.org/licenses/MIT
 
 [build-badge]: https://img.shields.io/github/actions/workflow/status/sebastienrousseau/html-generator/release.yml?branch=main&style=for-the-badge&logo=github
+
 [codecov-badge]: https://img.shields.io/codecov/c/github/sebastienrousseau/html-generator?style=for-the-badge&token=Q9KJ6XXL67&logo=codecov
 [crates-badge]: https://img.shields.io/crates/v/html-generator.svg?style=for-the-badge&color=fc8d62&logo=rust
-[docs-badge]: https://img.shields.io/badge/docs.rs-metadata--gen-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
-[github-badge]: https://img.shields.io/badge/github-sebastienrousseau/metadata--gen-8da0cb?style=for-the-badge&labelColor=555555&logo=github
+[docs-badge]: https://img.shields.io/badge/docs.rs-html--generator-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs
+[github-badge]: https://img.shields.io/badge/github-sebastienrousseau/html--generator-8da0cb?style=for-the-badge&labelColor=555555&logo=github
 [libs-badge]: https://img.shields.io/badge/lib.rs-v0.0.2-orange.svg?style=for-the-badge
 [made-with-rust]: https://img.shields.io/badge/rust-f04041?style=for-the-badge&labelColor=c0282d&logo=rust
diff --git a/examples/basic/amps-and-angle-encoding.txt b/examples/basic/amps-and-angle-encoding.txt
new file mode 100644
index 0000000..0e9527f
--- /dev/null
+++ b/examples/basic/amps-and-angle-encoding.txt
@@ -0,0 +1,21 @@
+AT&T has an ampersand in their name.
+
+AT&T is another way to write it.
+
+This & that.
+
+4 < 5.
+
+6 > 5.
+
+Here's a [link] [1] with an ampersand in the URL.
+
+Here's a link with an amersand in the link text: [AT&T] [2].
+
+Here's an inline [link](/script?foo=1&bar=2).
+
+Here's an inline [link]().
+
+
+[1]: http://example.com/?foo=1&bar=2
+[2]: http://att.com/  "AT&T"
\ No newline at end of file
diff --git a/examples/basic/angle-links-and-img.txt b/examples/basic/angle-links-and-img.txt
new file mode 100644
index 0000000..1dbf404
--- /dev/null
+++ b/examples/basic/angle-links-and-img.txt
@@ -0,0 +1,4 @@
+[link]( "title")
+![image]()
+[link]()
+![image]()
diff --git a/examples/basic/auto-links.txt b/examples/basic/auto-links.txt
new file mode 100644
index 0000000..a188b40
--- /dev/null
+++ b/examples/basic/auto-links.txt
@@ -0,0 +1,17 @@
+Link: .
+
+Https link: 
+
+Ftp link: 
+
+With an ampersand: 
+
+* In a list?
+* 
+* It should.
+
+> Blockquoted: 
+
+Auto-links should not occur here: ``
+
+	or here: 
diff --git a/examples/basic/backlash-escapes.txt b/examples/basic/backlash-escapes.txt
new file mode 100644
index 0000000..16447a0
--- /dev/null
+++ b/examples/basic/backlash-escapes.txt
@@ -0,0 +1,104 @@
+These should all get escaped:
+
+Backslash: \\
+
+Backtick: \`
+
+Asterisk: \*
+
+Underscore: \_
+
+Left brace: \{
+
+Right brace: \}
+
+Left bracket: \[
+
+Right bracket: \]
+
+Left paren: \(
+
+Right paren: \)
+
+Greater-than: \>
+
+Hash: \#
+
+Period: \.
+
+Bang: \!
+
+Plus: \+
+
+Minus: \-
+
+
+
+These should not, because they occur within a code block:
+
+	Backslash: \\
+
+	Backtick: \`
+
+	Asterisk: \*
+
+	Underscore: \_
+
+	Left brace: \{
+
+	Right brace: \}
+
+	Left bracket: \[
+
+	Right bracket: \]
+
+	Left paren: \(
+
+	Right paren: \)
+
+	Greater-than: \>
+
+	Hash: \#
+
+	Period: \.
+
+	Bang: \!
+
+	Plus: \+
+
+	Minus: \-
+
+
+Nor should these, which occur in code spans:
+
+Backslash: `\\`
+
+Backtick: `` \` ``
+
+Asterisk: `\*`
+
+Underscore: `\_`
+
+Left brace: `\{`
+
+Right brace: `\}`
+
+Left bracket: `\[`
+
+Right bracket: `\]`
+
+Left paren: `\(`
+
+Right paren: `\)`
+
+Greater-than: `\>`
+
+Hash: `\#`
+
+Period: `\.`
+
+Bang: `\!`
+
+Plus: `\+`
+
+Minus: `\-`
diff --git a/examples/basic/blockquotes-with-code-blocks.txt b/examples/basic/blockquotes-with-code-blocks.txt
new file mode 100644
index 0000000..c31d171
--- /dev/null
+++ b/examples/basic/blockquotes-with-code-blocks.txt
@@ -0,0 +1,11 @@
+> Example:
+> 
+>     sub status {
+>         print "working";
+>     }
+> 
+> Or:
+> 
+>     sub status {
+>         return "working";
+>     }
diff --git a/examples/basic/code_syntax_highlighting.txt b/examples/basic/code_syntax_highlighting.txt
new file mode 100644
index 0000000..95d4cf2
--- /dev/null
+++ b/examples/basic/code_syntax_highlighting.txt
@@ -0,0 +1,30 @@
+# Code Syntax Highlighting
+
+```rust
+fn main() {
+    println!("Hello, world!");
+}
+
+```python
+def main():
+    print("Hello, world!")
+```
+
+```html
+
                Hello, world!
                
+```
+
+```markdown
+---
+
+### 8. **Inline and Reference Links**
+**File Name**: `links_variety.txt`
+```markdown
+# Inline and Reference Links
+
+[Inline Link](https://example.com "Inline Link Title")
+
+[Reference Link][1]
+
+[1]: https://example.com/reference "Reference Link Title"
+```
diff --git a/examples/basic/codeblock-in-list.txt b/examples/basic/codeblock-in-list.txt
new file mode 100644
index 0000000..87d4e3b
--- /dev/null
+++ b/examples/basic/codeblock-in-list.txt
@@ -0,0 +1,10 @@
+* A list item with a code block
+
+        Some *code*
+
+* Another list item
+
+        More code
+
+        And more code
+
diff --git a/examples/basic/custom_containers.txt b/examples/basic/custom_containers.txt
new file mode 100644
index 0000000..ad98e5d
--- /dev/null
+++ b/examples/basic/custom_containers.txt
@@ -0,0 +1,13 @@
+# Custom Containers
+
+::: note
+This is a note.
+:::
+
+::: warning
+This is a warning.
+:::
+
+::: success
+This is a success message.
+:::
diff --git a/examples/basic/edge_cases.txt b/examples/basic/edge_cases.txt
new file mode 100644
index 0000000..acf2085
--- /dev/null
+++ b/examples/basic/edge_cases.txt
@@ -0,0 +1,15 @@
+# Edge Cases
+
+
+
+#ThisIsNotAHeader
+Not separated by a space.
+
+##Multiple##Hashes##
+
+**No closing tag for bold
+*No closing tag for italic
+
+> Nested blockquote
+>> Another level
+>>> Yet another level
diff --git a/examples/basic/emoji_content.txt b/examples/basic/emoji_content.txt
new file mode 100644
index 0000000..224446f
--- /dev/null
+++ b/examples/basic/emoji_content.txt
@@ -0,0 +1,7 @@
+# Emoji Content
+
+🎉 Welcome to Emoji World! 😃
+
+🔥🔥🔥 This is a fire-themed section. 🚒
+
+🚀 Let's explore space!
diff --git a/examples/basic/escaped_characters.txt b/examples/basic/escaped_characters.txt
new file mode 100644
index 0000000..8630517
--- /dev/null
+++ b/examples/basic/escaped_characters.txt
@@ -0,0 +1,25 @@
+# Escaped Characters
+
+\\ This is a backslash.
+
+\` This is a backtick.
+
+\* This is an asterisk.
+
+\_ This is an underscore.
+
+\{ This is a curly brace.
+
+\[ This is a square bracket.
+
+\( This is a parenthesis.
+
+\# This is a hash.
+
+\+ This is a plus sign.
+
+\- This is a hyphen.
+
+\. This is a period.
+
+\! This is an exclamation mark.
diff --git a/examples/basic/hard-wrapped.txt b/examples/basic/hard-wrapped.txt
new file mode 100644
index 0000000..f8a5b27
--- /dev/null
+++ b/examples/basic/hard-wrapped.txt
@@ -0,0 +1,8 @@
+In Markdown 1.0.0 and earlier. Version
+8. This line turns into a list item.
+Because a hard-wrapped line in the
+middle of a paragraph looked like a
+list item.
+
+Here's one with a bullet.
+* criminey.
diff --git a/examples/basic/horizontal-rules.txt b/examples/basic/horizontal-rules.txt
new file mode 100644
index 0000000..1594bda
--- /dev/null
+++ b/examples/basic/horizontal-rules.txt
@@ -0,0 +1,67 @@
+Dashes:
+
+---
+
+ ---
+ 
+  ---
+
+   ---
+
+	---
+
+- - -
+
+ - - -
+ 
+  - - -
+
+   - - -
+
+	- - -
+
+
+Asterisks:
+
+***
+
+ ***
+ 
+  ***
+
+   ***
+
+	***
+
+* * *
+
+ * * *
+ 
+  * * *
+
+   * * *
+
+	* * *
+
+
+Underscores:
+
+___
+
+ ___
+ 
+  ___
+
+   ___
+
+    ___
+
+_ _ _
+
+ _ _ _
+ 
+  _ _ _
+
+   _ _ _
+
+    _ _ _
diff --git a/examples/basic/large_markdown.txt b/examples/basic/large_markdown.txt
new file mode 100644
index 0000000..b2ffdeb
--- /dev/null
+++ b/examples/basic/large_markdown.txt
@@ -0,0 +1,29 @@
+# Large Markdown File
+
+This file contains a large number of headers, paragraphs, and lists.
+
+---
+
+## Section 1
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse ultrices urna nec volutpat vehicula. Nullam lacinia ex nec nulla dignissim.
+
+1. Item 1
+2. Item 2
+3. Item 3
+
+---
+
+## Section 2
+
+Praesent nec dui bibendum, congue justo vel, sollicitudin mi. Cras tincidunt dui sit amet turpis egestas fermentum.
+
+| Header | Header | Header |
+|--------|--------|--------|
+| Cell   | Cell   | Cell   |
+| Cell   | Cell   | Cell   |
+| Cell   | Cell   | Cell   |
+
+---
+
+*This file contains 500 more lines of content.*
diff --git a/examples/basic/links-inline.txt b/examples/basic/links-inline.txt
new file mode 100644
index 0000000..4d0c1c2
--- /dev/null
+++ b/examples/basic/links-inline.txt
@@ -0,0 +1,9 @@
+Just a [URL](/url/).
+
+[URL and title](/url/ "title").
+
+[URL and title](/url/  "title preceded by two spaces").
+
+[URL and title](/url/	"title preceded by a tab").
+
+[Empty]().
diff --git a/examples/basic/links-reference.txt b/examples/basic/links-reference.txt
new file mode 100644
index 0000000..3d636e5
--- /dev/null
+++ b/examples/basic/links-reference.txt
@@ -0,0 +1,61 @@
+Foo [bar] [1].
+
+Foo [bar][1].
+
+Foo [bar]
+[1].
+
+[1]: /url/  "Title"
+
+
+With [embedded [brackets]] [b].
+
+
+Indented [once][].
+
+Indented [twice][].
+
+Indented [thrice][].
+
+Indented [four][] times.
+
+ [once]: /url
+
+  [twice]: /url
+
+   [thrice]: /url
+
+    [four]: /url
+
+
+[b]: /url/
+
+With [angle brackets][].
+
+And [without][].
+
+[angle brackets]:  "Angle Brackets"
+[without]: http://example.com/ "Without angle brackets."
+
+With [line
+breaks][]
+
+and [line 
+breaks][] with one space.
+
+and [line  
+breaks[] with two spaces.
+
+[line breaks]: http://example.com "Yes this works"
+
+[short ref]
+
+[short 
+ref]
+
+[short ref]: http://example.com "No more hanging empty bracket!"
+
+[a ref]
+
+[a ref]: http://example.com
+    "Title on next line."
diff --git a/examples/basic/literal-quotes.txt b/examples/basic/literal-quotes.txt
new file mode 100644
index 0000000..29d0e42
--- /dev/null
+++ b/examples/basic/literal-quotes.txt
@@ -0,0 +1,7 @@
+Foo [bar][].
+
+Foo [bar](/url/ "Title with "quotes" inside").
+
+
+  [bar]: /url/ "Title with "quotes" inside"
+
diff --git a/examples/basic/markdown-documentation-basics.txt b/examples/basic/markdown-documentation-basics.txt
new file mode 100644
index 0000000..b0932f3
--- /dev/null
+++ b/examples/basic/markdown-documentation-basics.txt
@@ -0,0 +1,306 @@
+Markdown: Basics
+================
+
+
+
+
+Getting the Gist of Markdown's Formatting Syntax
+------------------------------------------------
+
+This page offers a brief overview of what it's like to use Markdown.
+The [syntax page] [s] provides complete, detailed documentation for
+every feature, but Markdown should be very easy to pick up simply by
+looking at a few examples of it in action. The examples on this page
+are written in a before/after style, showing example syntax and the
+HTML output produced by Markdown.
+
+It's also helpful to simply try Markdown out; the [Dingus] [d] is a
+web application that allows you type your own Markdown-formatted text
+and translate it to XHTML.
+
+**Note:** This document is itself written using Markdown; you
+can [see the source for it by adding '.text' to the URL] [src].
+
+  [s]: /projects/markdown/syntax  "Markdown Syntax"
+  [d]: /projects/markdown/dingus  "Markdown Dingus"
+  [src]: /projects/markdown/basics.text
+
+
+## Paragraphs, Headers, Blockquotes ##
+
+A paragraph is simply one or more consecutive lines of text, separated
+by one or more blank lines. (A blank line is any line that looks like a
+blank line -- a line containing nothing spaces or tabs is considered
+blank.) Normal paragraphs should not be indented with spaces or tabs.
+
+Markdown offers two styles of headers: *Setext* and *atx*.
+Setext-style headers for `
                ` and `
                ` are created by
+"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
+To create an atx-style header, you put 1-6 hash marks (`#`) at the
+beginning of the line -- the number of hashes equals the resulting
+HTML header level.
+
+Blockquotes are indicated using email-style '`>`' angle brackets.
+
+Markdown:
+
+    A First Level Header
+    ====================
+    
+    A Second Level Header
+    ---------------------
+
+    Now is the time for all good men to come to
+    the aid of their country. This is just a
+    regular paragraph.
+
+    The quick brown fox jumped over the lazy
+    dog's back.
+    
+    ### Header 3
+
+    > This is a blockquote.
+    > 
+    > This is the second paragraph in the blockquote.
+    >
+    > ## This is an H2 in a blockquote
+
+
+Output:
+
+    
                A First Level Header
                
+    
+    
                A Second Level Header
                
+    
+    
                Now is the time for all good men to come to
+    the aid of their country. This is just a
+    regular paragraph.
                
+    
+    
                The quick brown fox jumped over the lazy
+    dog's back.
                
+    
+    
                Header 3
                
+    
+    
                
+        
                This is a blockquote.
                
+        
+        
                This is the second paragraph in the blockquote.
                
+        
+        
                This is an H2 in a blockquote
                
+    
                
+
+
+
+### Phrase Emphasis ###
+
+Markdown uses asterisks and underscores to indicate spans of emphasis.
+
+Markdown:
+
+    Some of these words *are emphasized*.
+    Some of these words _are emphasized also_.
+    
+    Use two asterisks for **strong emphasis**.
+    Or, if you prefer, __use two underscores instead__.
+
+Output:
+
+    
                Some of these words are emphasized.
+    Some of these words are emphasized also.
                
+    
+    
                Use two asterisks for strong emphasis.
+    Or, if you prefer, use two underscores instead.
                
+   
+
+
+## Lists ##
+
+Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
+`+`, and `-`) as list markers. These three markers are
+interchangeable; this:
+
+    *   Candy.
+    *   Gum.
+    *   Booze.
+
+this:
+
+    +   Candy.
+    +   Gum.
+    +   Booze.
+
+and this:
+
+    -   Candy.
+    -   Gum.
+    -   Booze.
+
+all produce the same output:
+
+    
                  
+    
                • Candy.
                  • 
+    
                • Gum.
                  • 
+    
                • Booze.
                  • 
+    
                
+
+Ordered (numbered) lists use regular numbers, followed by periods, as
+list markers:
+
+    1.  Red
+    2.  Green
+    3.  Blue
+
+Output:
+
+    
                  
+    
                1. Red
                  2. 
+    
                2. Green
                  3. 
+    
                3. Blue
                  4. 
+    
                
+
+If you put blank lines between items, you'll get `
                ` tags for the
+list item text. You can create multi-paragraph list items by indenting
+the paragraphs by 4 spaces or 1 tab:
+
+    *   A list item.
+    
+        With multiple paragraphs.
+
+    *   Another item in the list.
+
+Output:
+
+    
                  
+    
                • A list item.
                  
+    
                  With multiple paragraphs.
                  • 
+    
                • Another item in the list.
                  • 
+    
                
+    
+
+
+### Links ###
+
+Markdown supports two styles for creating links: *inline* and
+*reference*. With both styles, you use square brackets to delimit the
+text you want to turn into a link.
+
+Inline-style links use parentheses immediately after the link text.
+For example:
+
+    This is an [example link](http://example.com/).
+
+Output:
+
+    
                This is an 
+    example link.
                
+
+Optionally, you may include a title attribute in the parentheses:
+
+    This is an [example link](http://example.com/ "With a Title").
+
+Output:
+
+    
                This is an 
+    example link.
                
+
+Reference-style links allow you to refer to your links by names, which
+you define elsewhere in your document:
+
+    I get 10 times more traffic from [Google][1] than from
+    [Yahoo][2] or [MSN][3].
+
+    [1]: http://google.com/        "Google"
+    [2]: http://search.yahoo.com/  "Yahoo Search"
+    [3]: http://search.msn.com/    "MSN Search"
+
+Output:
+
+    
                I get 10 times more traffic from Google than from Yahoo or MSN.
                
+
+The title attribute is optional. Link names may contain letters,
+numbers and spaces, but are *not* case sensitive:
+
+    I start my morning with a cup of coffee and
+    [The New York Times][NY Times].
+
+    [ny times]: http://www.nytimes.com/
+
+Output:
+
+    
                I start my morning with a cup of coffee and
+    The New York Times.
                
+
+
+### Images ###
+
+Image syntax is very much like link syntax.
+
+Inline (titles are optional):
+
+    ![alt text](/path/to/img.jpg "Title")
+
+Reference-style:
+
+    ![alt text][id]
+
+    [id]: /path/to/img.jpg "Title"
+
+Both of the above examples produce the same output:
+
+    alt text
+
+
+
+### Code ###
+
+In a regular paragraph, you can create code span by wrapping text in
+backtick quotes. Any ampersands (`&`) and angle brackets (`<` or
+`>`) will automatically be translated into HTML entities. This makes
+it easy to use Markdown to write about HTML example code:
+
+    I strongly recommend against using any `` tags.
+
+    I wish SmartyPants used named entities like `—`
+    instead of decimal-encoded entities like `—`.
+
+Output:
+
+    
                I strongly recommend against using any
+    <blink> tags.
                
+    
+    
                I wish SmartyPants used named entities like
+    &mdash; instead of decimal-encoded
+    entities like &#8212;.
                
+
+
+To specify an entire block of pre-formatted code, indent every line of
+the block by 4 spaces or 1 tab. Just like with code spans, `&`, `<`,
+and `>` characters will be escaped automatically.
+
+Markdown:
+
+    If you want your page to validate under XHTML 1.0 Strict,
+    you've got to put paragraph tags in your blockquotes:
+
+        
                
+            
                For example.
                
+        
                
+
+Output:
+
+    
                If you want your page to validate under XHTML 1.0 Strict,
+    you've got to put paragraph tags in your blockquotes:
                
+    
+    
                <blockquote>
+        <p>For example.</p>
+    </blockquote>
+    
                
diff --git a/examples/basic/markdown-syntax.txt b/examples/basic/markdown-syntax.txt
new file mode 100644
index 0000000..38f6e78
--- /dev/null
+++ b/examples/basic/markdown-syntax.txt
@@ -0,0 +1,888 @@
+Markdown: Syntax
+================
+
+
+
+
+*   [Overview](#overview)
+    *   [Philosophy](#philosophy)
+    *   [Inline HTML](#html)
+    *   [Automatic Escaping for Special Characters](#autoescape)
+*   [Block Elements](#block)
+    *   [Paragraphs and Line Breaks](#p)
+    *   [Headers](#header)
+    *   [Blockquotes](#blockquote)
+    *   [Lists](#list)
+    *   [Code Blocks](#precode)
+    *   [Horizontal Rules](#hr)
+*   [Span Elements](#span)
+    *   [Links](#link)
+    *   [Emphasis](#em)
+    *   [Code](#code)
+    *   [Images](#img)
+*   [Miscellaneous](#misc)
+    *   [Backslash Escapes](#backslash)
+    *   [Automatic Links](#autolink)
+
+
+**Note:** This document is itself written using Markdown; you
+can [see the source for it by adding '.text' to the URL][src].
+
+  [src]: /projects/markdown/syntax.text
+
+* * *
+
+
                Overview
                
+
+
                Philosophy
                
+
+Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
+
+Readability, however, is emphasized above all else. A Markdown-formatted
+document should be publishable as-is, as plain text, without looking
+like it's been marked up with tags or formatting instructions. While
+Markdown's syntax has been influenced by several existing text-to-HTML
+filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
+[Grutatext] [5], and [EtText] [6] -- the single biggest source of
+inspiration for Markdown's syntax is the format of plain text email.
+
+  [1]: http://docutils.sourceforge.net/mirror/setext.html
+  [2]: http://www.aaronsw.com/2002/atx/
+  [3]: http://textism.com/tools/textile/
+  [4]: http://docutils.sourceforge.net/rst.html
+  [5]: http://www.triptico.com/software/grutatxt.html
+  [6]: http://ettext.taint.org/doc/
+
+To this end, Markdown's syntax is comprised entirely of punctuation
+characters, which punctuation characters have been carefully chosen so
+as to look like what they mean. E.g., asterisks around a word actually
+look like \*emphasis\*. Markdown lists look like, well, lists. Even
+blockquotes look like quoted passages of text, assuming you've ever
+used email.
+
+
+
+
                Inline HTML
                
+
+Markdown's syntax is intended for one purpose: to be used as a
+format for *writing* for the web.
+
+Markdown is not a replacement for HTML, or even close to it. Its
+syntax is very small, corresponding only to a very small subset of
+HTML tags. The idea is *not* to create a syntax that makes it easier
+to insert HTML tags. In my opinion, HTML tags are already easy to
+insert. The idea for Markdown is to make it easy to read, write, and
+edit prose. HTML is a *publishing* format; Markdown is a *writing*
+format. Thus, Markdown's formatting syntax only addresses issues that
+can be conveyed in plain text.
+
+For any markup that is not covered by Markdown's syntax, you simply
+use HTML itself. There's no need to preface it or delimit it to
+indicate that you're switching from Markdown to HTML; you just use
+the tags.
+
+The only restrictions are that block-level HTML elements -- e.g. `
                `,
+``, `
                `, `
                `, etc. -- must be separated from surrounding
+content by blank lines, and the start and end tags of the block should
+not be indented with tabs or spaces. Markdown is smart enough not
+to add extra (unwanted) `
                ` tags around HTML block-level tags.
+
+For example, to add an HTML table to a Markdown article:
+
+    This is a regular paragraph.
+
+    
                
+        
+            
+        
+    
                Foo
                
+
+    This is another regular paragraph.
+
+Note that Markdown formatting syntax is not processed within block-level
+HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
+HTML block.
+
+Span-level HTML tags -- e.g. ``, ``, or `` -- can be
+used anywhere in a Markdown paragraph, list item, or header. If you
+want, you can even use HTML tags instead of Markdown formatting; e.g. if
+you'd prefer to use HTML `` or `` tags instead of Markdown's
+link or image syntax, go right ahead.
+
+Unlike block-level HTML tags, Markdown syntax *is* processed within
+span-level tags.
+
+
+
                Automatic Escaping for Special Characters
                
+
+In HTML, there are two characters that demand special treatment: `<`
+and `&`. Left angle brackets are used to start tags; ampersands are
+used to denote HTML entities. If you want to use them as literal
+characters, you must escape them as entities, e.g. `<`, and
+`&`.
+
+Ampersands in particular are bedeviling for web writers. If you want to
+write about 'AT&T', you need to write '`AT&T`'. You even need to
+escape ampersands within URLs. Thus, if you want to link to:
+
+    http://images.google.com/images?num=30&q=larry+bird
+
+you need to encode the URL as:
+
+    http://images.google.com/images?num=30&q=larry+bird
+
+in your anchor tag `href` attribute. Needless to say, this is easy to
+forget, and is probably the single most common source of HTML validation
+errors in otherwise well-marked-up web sites.
+
+Markdown allows you to use these characters naturally, taking care of
+all the necessary escaping for you. If you use an ampersand as part of
+an HTML entity, it remains unchanged; otherwise it will be translated
+into `&`.
+
+So, if you want to include a copyright symbol in your article, you can write:
+
+    ©
+
+and Markdown will leave it alone. But if you write:
+
+    AT&T
+
+Markdown will translate it to:
+
+    AT&T
+
+Similarly, because Markdown supports [inline HTML](#html), if you use
+angle brackets as delimiters for HTML tags, Markdown will treat them as
+such. But if you write:
+
+    4 < 5
+
+Markdown will translate it to:
+
+    4 < 5
+
+However, inside Markdown code spans and blocks, angle brackets and
+ampersands are *always* encoded automatically. This makes it easy to use
+Markdown to write about HTML code. (As opposed to raw HTML, which is a
+terrible format for writing about HTML syntax, because every single `<`
+and `&` in your example code needs to be escaped.)
+
+
+* * *
+
+
+
                Block Elements
                
+
+
+
                Paragraphs and Line Breaks
                
+
+A paragraph is simply one or more consecutive lines of text, separated
+by one or more blank lines. (A blank line is any line that looks like a
+blank line -- a line containing nothing but spaces or tabs is considered
+blank.) Normal paragraphs should not be indented with spaces or tabs.
+
+The implication of the "one or more consecutive lines of text" rule is
+that Markdown supports "hard-wrapped" text paragraphs. This differs
+significantly from most other text-to-HTML formatters (including Movable
+Type's "Convert Line Breaks" option) which translate every line break
+character in a paragraph into a `
                ` tag.
+
+When you *do* want to insert a `
                ` break tag using Markdown, you
+end a line with two or more spaces, then type return.
+
+Yes, this takes a tad more effort to create a `
                `, but a simplistic
+"every line break is a `
                `" rule wouldn't work for Markdown.
+Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
+work best -- and look better -- when you format them with hard breaks.
+
+  [bq]: #blockquote
+  [l]:  #list
+
+
+
+
+
+Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
+
+Setext-style headers are "underlined" using equal signs (for first-level
+headers) and dashes (for second-level headers). For example:
+
+    This is an H1
+    =============
+
+    This is an H2
+    -------------
+
+Any number of underlining `=`'s or `-`'s will work.
+
+Atx-style headers use 1-6 hash characters at the start of the line,
+corresponding to header levels 1-6. For example:
+
+    # This is an H1
+
+    ## This is an H2
+
+    ###### This is an H6
+
+Optionally, you may "close" atx-style headers. This is purely
+cosmetic -- you can use this if you think it looks better. The
+closing hashes don't even need to match the number of hashes
+used to open the header. (The number of opening hashes
+determines the header level.) :
+
+    # This is an H1 #
+
+    ## This is an H2 ##
+
+    ### This is an H3 ######
+
+
+
                Blockquotes
                
+
+Markdown uses email-style `>` characters for blockquoting. If you're
+familiar with quoting passages of text in an email message, then you
+know how to create a blockquote in Markdown. It looks best if you hard
+wrap the text and put a `>` before every line:
+
+    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+    > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+    > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+    > 
+    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+    > id sem consectetuer libero luctus adipiscing.
+
+Markdown allows you to be lazy and only put the `>` before the first
+line of a hard-wrapped paragraph:
+
+    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+    consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+
+    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+    id sem consectetuer libero luctus adipiscing.
+
+Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
+adding additional levels of `>`:
+
+    > This is the first level of quoting.
+    >
+    > > This is nested blockquote.
+    >
+    > Back to the first level.
+
+Blockquotes can contain other Markdown elements, including headers, lists,
+and code blocks:
+
+	> ## This is a header.
+	> 
+	> 1.   This is the first list item.
+	> 2.   This is the second list item.
+	> 
+	> Here's some example code:
+	> 
+	>     return shell_exec("echo $input | $markdown_script");
+
+Any decent text editor should make email-style quoting easy. For
+example, with BBEdit, you can make a selection and choose Increase
+Quote Level from the Text menu.
+
+
+
                Lists
                
+
+Markdown supports ordered (numbered) and unordered (bulleted) lists.
+
+Unordered lists use asterisks, pluses, and hyphens -- interchangeably
+-- as list markers:
+
+    *   Red
+    *   Green
+    *   Blue
+
+is equivalent to:
+
+    +   Red
+    +   Green
+    +   Blue
+
+and:
+
+    -   Red
+    -   Green
+    -   Blue
+
+Ordered lists use numbers followed by periods:
+
+    1.  Bird
+    2.  McHale
+    3.  Parish
+
+It's important to note that the actual numbers you use to mark the
+list have no effect on the HTML output Markdown produces. The HTML
+Markdown produces from the above list is:
+
+    
                  
+    
                1. Bird
                  2. 
+    
                2. McHale
                  3. 
+    
                3. Parish
                  4. 
+    
                
+
+If you instead wrote the list in Markdown like this:
+
+    1.  Bird
+    1.  McHale
+    1.  Parish
+
+or even:
+
+    3. Bird
+    1. McHale
+    8. Parish
+
+you'd get the exact same HTML output. The point is, if you want to,
+you can use ordinal numbers in your ordered Markdown lists, so that
+the numbers in your source match the numbers in your published HTML.
+But if you want to be lazy, you don't have to.
+
+If you do use lazy list numbering, however, you should still start the
+list with the number 1. At some point in the future, Markdown may support
+starting ordered lists at an arbitrary number.
+
+List markers typically start at the left margin, but may be indented by
+up to three spaces. List markers must be followed by one or more spaces
+or a tab.
+
+To make lists look nice, you can wrap items with hanging indents:
+
+    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+        Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+        viverra nec, fringilla in, laoreet vitae, risus.
+    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+        Suspendisse id sem consectetuer libero luctus adipiscing.
+
+But if you want to be lazy, you don't have to:
+
+    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+    viverra nec, fringilla in, laoreet vitae, risus.
+    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+    Suspendisse id sem consectetuer libero luctus adipiscing.
+
+If list items are separated by blank lines, Markdown will wrap the
+items in `
                ` tags in the HTML output. For example, this input:
+
+    *   Bird
+    *   Magic
+
+will turn into:
+
+    
                  
+    
                • Bird
                  • 
+    
                • Magic
                  • 
+    
                
+
+But this:
+
+    *   Bird
+
+    *   Magic
+
+will turn into:
+
+    
                  
+    
                • Bird
                  • 
+    
                • Magic
                  • 
+    
                
+
+List items may consist of multiple paragraphs. Each subsequent
+paragraph in a list item must be indented by either 4 spaces
+or one tab:
+
+    1.  This is a list item with two paragraphs. Lorem ipsum dolor
+        sit amet, consectetuer adipiscing elit. Aliquam hendrerit
+        mi posuere lectus.
+
+        Vestibulum enim wisi, viverra nec, fringilla in, laoreet
+        vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
+        sit amet velit.
+
+    2.  Suspendisse id sem consectetuer libero luctus adipiscing.
+
+It looks nice if you indent every line of the subsequent
+paragraphs, but here again, Markdown will allow you to be
+lazy:
+
+    *   This is a list item with two paragraphs.
+
+        This is the second paragraph in the list item. You're
+    only required to indent the first line. Lorem ipsum dolor
+    sit amet, consectetuer adipiscing elit.
+
+    *   Another item in the same list.
+
+To put a blockquote within a list item, the blockquote's `>`
+delimiters need to be indented:
+
+    *   A list item with a blockquote:
+
+        > This is a blockquote
+        > inside a list item.
+
+To put a code block within a list item, the code block needs
+to be indented *twice* -- 8 spaces or two tabs:
+
+    *   A list item with a code block:
+
+            
+
+
+It's worth noting that it's possible to trigger an ordered list by
+accident, by writing something like this:
+
+    1986. What a great season.
+
+In other words, a *number-period-space* sequence at the beginning of a
+line. To avoid this, you can backslash-escape the period:
+
+    1986\. What a great season.
+
+
+
+
                Code Blocks
                
+
+Pre-formatted code blocks are used for writing about programming or
+markup source code. Rather than forming normal paragraphs, the lines
+of a code block are interpreted literally. Markdown wraps a code block
+in both `
                ` and `` tags.
+
+To produce a code block in Markdown, simply indent every line of the
+block by at least 4 spaces or 1 tab. For example, given this input:
+
+    This is a normal paragraph:
+
+        This is a code block.
+
+Markdown will generate:
+
+    
                This is a normal paragraph:
                
+
+    
                This is a code block.
+    
                
+
+One level of indentation -- 4 spaces or 1 tab -- is removed from each
+line of the code block. For example, this:
+
+    Here is an example of AppleScript:
+
+        tell application "Foo"
+            beep
+        end tell
+
+will turn into:
+
+    
                Here is an example of AppleScript:
                
+
+    
                tell application "Foo"
+        beep
+    end tell
+    
                
+
+A code block continues until it reaches a line that is not indented
+(or the end of the article).
+
+Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
+are automatically converted into HTML entities. This makes it very
+easy to include example HTML source code using Markdown -- just paste
+it and indent it, and Markdown will handle the hassle of encoding the
+ampersands and angle brackets. For example, this:
+
+        
                
+            © 2004 Foo Corporation
+        
                
+
+will turn into:
+
+    
                <div class="footer">
+        &copy; 2004 Foo Corporation
+    </div>
+    
                
+
+Regular Markdown syntax is not processed within code blocks. E.g.,
+asterisks are just literal asterisks within a code block. This means
+it's also easy to use Markdown to write about Markdown's own syntax.
+
+
+
+
                Horizontal Rules
                
+
+You can produce a horizontal rule tag (`
                `) by placing three or
+more hyphens, asterisks, or underscores on a line by themselves. If you
+wish, you may use spaces between the hyphens or asterisks. Each of the
+following lines will produce a horizontal rule:
+
+    * * *
+
+    ***
+
+    *****
+	
+    - - -
+
+    ---------------------------------------
+
+	_ _ _
+
+
+* * *
+
+
                Span Elements
                
+
+
+
+Markdown supports two style of links: *inline* and *reference*.
+
+In both styles, the link text is delimited by [square brackets].
+
+To create an inline link, use a set of regular parentheses immediately
+after the link text's closing square bracket. Inside the parentheses,
+put the URL where you want the link to point, along with an *optional*
+title for the link, surrounded in quotes. For example:
+
+    This is [an example](http://example.com/ "Title") inline link.
+
+    [This link](http://example.net/) has no title attribute.
+
+Will produce:
+
+    
                This is 
+    an example inline link.
                
+
+    
                This link has no
+    title attribute.
                
+
+If you're referring to a local resource on the same server, you can
+use relative paths:
+
+    See my [About](/about/) page for details.   
+
+Reference-style links use a second set of square brackets, inside
+which you place a label of your choosing to identify the link:
+
+    This is [an example][id] reference-style link.
+
+You can optionally use a space to separate the sets of brackets:
+
+    This is [an example] [id] reference-style link.
+
+Then, anywhere in the document, you define your link label like this,
+on a line by itself:
+
+    [id]: http://example.com/  "Optional Title Here"
+
+That is:
+
+*   Square brackets containing the link identifier (optionally
+    indented from the left margin using up to three spaces);
+*   followed by a colon;
+*   followed by one or more spaces (or tabs);
+*   followed by the URL for the link;
+*   optionally followed by a title attribute for the link, enclosed
+    in double or single quotes.
+
+The link URL may, optionally, be surrounded by angle brackets:
+
+    [id]:   "Optional Title Here"
+
+You can put the title attribute on the next line and use extra spaces
+or tabs for padding, which tends to look better with longer URLs:
+
+    [id]: http://example.com/longish/path/to/resource/here
+        "Optional Title Here"
+
+Link definitions are only used for creating links during Markdown
+processing, and are stripped from your document in the HTML output.
+
+Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
+
+	[link text][a]
+	[link text][A]
+
+are equivalent.
+
+The *implicit link name* shortcut allows you to omit the name of the
+link, in which case the link text itself is used as the name.
+Just use an empty set of square brackets -- e.g., to link the word
+"Google" to the google.com web site, you could simply write:
+
+	[Google][]
+
+And then define the link:
+
+	[Google]: http://google.com/
+
+Because link names may contain spaces, this shortcut even works for
+multiple words in the link text:
+
+	Visit [Daring Fireball][] for more information.
+
+And then define the link:
+	
+	[Daring Fireball]: http://daringfireball.net/
+
+Link definitions can be placed anywhere in your Markdown document. I
+tend to put them immediately after each paragraph in which they're
+used, but if you want, you can put them all at the end of your
+document, sort of like footnotes.
+
+Here's an example of reference links in action:
+
+    I get 10 times more traffic from [Google] [1] than from
+    [Yahoo] [2] or [MSN] [3].
+
+      [1]: http://google.com/        "Google"
+      [2]: http://search.yahoo.com/  "Yahoo Search"
+      [3]: http://search.msn.com/    "MSN Search"
+
+Using the implicit link name shortcut, you could instead write:
+
+    I get 10 times more traffic from [Google][] than from
+    [Yahoo][] or [MSN][].
+
+      [google]: http://google.com/        "Google"
+      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
+      [msn]:    http://search.msn.com/    "MSN Search"
+
+Both of the above examples will produce the following HTML output:
+
+    
                I get 10 times more traffic from Google than from
+    Yahoo
+    or MSN.
                
+
+For comparison, here is the same paragraph written using
+Markdown's inline link style:
+
+    I get 10 times more traffic from [Google](http://google.com/ "Google")
+    than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
+    [MSN](http://search.msn.com/ "MSN Search").
+
+The point of reference-style links is not that they're easier to
+write. The point is that with reference-style links, your document
+source is vastly more readable. Compare the above examples: using
+reference-style links, the paragraph itself is only 81 characters
+long; with inline-style links, it's 176 characters; and as raw HTML,
+it's 234 characters. In the raw HTML, there's more markup than there
+is text.
+
+With Markdown's reference-style links, a source document much more
+closely resembles the final output, as rendered in a browser. By
+allowing you to move the markup-related metadata out of the paragraph,
+you can add links without interrupting the narrative flow of your
+prose.
+
+
+
                Emphasis
                
+
+Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
+emphasis. Text wrapped with one `*` or `_` will be wrapped with an
+HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML
+`` tag. E.g., this input:
+
+    *single asterisks*
+
+    _single underscores_
+
+    **double asterisks**
+
+    __double underscores__
+
+will produce:
+
+    single asterisks
+
+    single underscores
+
+    double asterisks
+
+    double underscores
+
+You can use whichever style you prefer; the lone restriction is that
+the same character must be used to open and close an emphasis span.
+
+Emphasis can be used in the middle of a word:
+
+    un*fucking*believable
+
+But if you surround an `*` or `_` with spaces, it'll be treated as a
+literal asterisk or underscore.
+
+To produce a literal asterisk or underscore at a position where it
+would otherwise be used as an emphasis delimiter, you can backslash
+escape it:
+
+    \*this text is surrounded by literal asterisks\*
+
+
+
+
                Code
                
+
+To indicate a span of code, wrap it with backtick quotes (`` ` ``).
+Unlike a pre-formatted code block, a code span indicates code within a
+normal paragraph. For example:
+
+    Use the `printf()` function.
+
+will produce:
+
+    
                Use the printf() function.
                
+
+To include a literal backtick character within a code span, you can use
+multiple backticks as the opening and closing delimiters:
+
+    ``There is a literal backtick (`) here.``
+
+which will produce this:
+
+    
                There is a literal backtick (`) here.
                
+
+The backtick delimiters surrounding a code span may include spaces --
+one after the opening, one before the closing. This allows you to place
+literal backtick characters at the beginning or end of a code span:
+
+	A single backtick in a code span: `` ` ``
+	
+	A backtick-delimited string in a code span: `` `foo` ``
+
+will produce:
+
+	
                A single backtick in a code span: `
                
+	
+	
                A backtick-delimited string in a code span: `foo`
                
+
+With a code span, ampersands and angle brackets are encoded as HTML
+entities automatically, which makes it easy to include example HTML
+tags. Markdown will turn this:
+
+    Please don't use any `` tags.
+
+into:
+
+    
                Please don't use any <blink> tags.
                
+
+You can write this:
+
+    `—` is the decimal-encoded equivalent of `—`.
+
+to produce:
+
+    
                &#8212; is the decimal-encoded
+    equivalent of &mdash;.
                
+
+
+
+
                Images
                
+
+Admittedly, it's fairly difficult to devise a "natural" syntax for
+placing images into a plain text document format.
+
+Markdown uses an image syntax that is intended to resemble the syntax
+for links, allowing for two styles: *inline* and *reference*.
+
+Inline image syntax looks like this:
+
+    ![Alt text](/path/to/img.jpg)
+
+    ![Alt text](/path/to/img.jpg "Optional title")
+
+That is:
+
+*   An exclamation mark: `!`;
+*   followed by a set of square brackets, containing the `alt`
+    attribute text for the image;
+*   followed by a set of parentheses, containing the URL or path to
+    the image, and an optional `title` attribute enclosed in double
+    or single quotes.
+
+Reference-style image syntax looks like this:
+
+    ![Alt text][id]
+
+Where "id" is the name of a defined image reference. Image references
+are defined using syntax identical to link references:
+
+    [id]: url/to/image  "Optional title attribute"
+
+As of this writing, Markdown has no syntax for specifying the
+dimensions of an image; if this is important to you, you can simply
+use regular HTML `` tags.
+
+
+* * *
+
+
+
                Miscellaneous
                
+
+
+
+Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
+
+    
+    
+Markdown will turn this into:
+
+    http://example.com/
+
+Automatic links for email addresses work similarly, except that
+Markdown will also perform a bit of randomized decimal and hex
+entity-encoding to help obscure your address from address-harvesting
+spambots. For example, Markdown will turn this:
+
+    
+
+into something like this:
+
+    address@exa
+    mple.com
+
+which will render in a browser as a clickable link to "address@example.com".
+
+(This sort of entity-encoding trick will indeed fool many, if not
+most, address-harvesting bots, but it definitely won't fool all of
+them. It's better than nothing, but an address published in this way
+will probably eventually start receiving spam.)
+
+
+
+
                Backslash Escapes
                
+
+Markdown allows you to use backslash escapes to generate literal
+characters which would otherwise have special meaning in Markdown's
+formatting syntax. For example, if you wanted to surround a word with
+literal asterisks (instead of an HTML `` tag), you can backslashes
+before the asterisks, like this:
+
+    \*literal asterisks\*
+
+Markdown provides backslash escapes for the following characters:
+
+    \   backslash
+    `   backtick
+    *   asterisk
+    _   underscore
+    {}  curly braces
+    []  square brackets
+    ()  parentheses
+    #   hash mark
+	+	plus sign
+	-	minus sign (hyphen)
+    .   dot
+    !   exclamation mark
+
diff --git a/examples/basic/nested-blockquotes.txt b/examples/basic/nested-blockquotes.txt
new file mode 100644
index 0000000..ed3c624
--- /dev/null
+++ b/examples/basic/nested-blockquotes.txt
@@ -0,0 +1,5 @@
+> foo
+>
+> > bar
+>
+> foo
diff --git a/examples/basic/ordered-and-unordered-list.txt b/examples/basic/ordered-and-unordered-list.txt
new file mode 100644
index 0000000..621db58
--- /dev/null
+++ b/examples/basic/ordered-and-unordered-list.txt
@@ -0,0 +1,122 @@
+## Unordered
+
+Asterisks tight:
+
+*	asterisk 1
+*	asterisk 2
+*	asterisk 3
+
+
+Asterisks loose:
+
+*	asterisk 1
+
+*	asterisk 2
+
+*	asterisk 3
+
+* * *
+
+Pluses tight:
+
++	Plus 1
++	Plus 2
++	Plus 3
+
+
+Pluses loose:
+
++	Plus 1
+
++	Plus 2
+
++	Plus 3
+
+* * *
+
+
+Minuses tight:
+
+-	Minus 1
+-	Minus 2
+-	Minus 3
+
+
+Minuses loose:
+
+-	Minus 1
+
+-	Minus 2
+
+-	Minus 3
+
+
+## Ordered
+
+Tight:
+
+1.	First
+2.	Second
+3.	Third
+
+and:
+
+1. One
+2. Two
+3. Three
+
+
+Loose using tabs:
+
+1.	First
+
+2.	Second
+
+3.	Third
+
+and using spaces:
+
+1. One
+
+2. Two
+
+3. Three
+
+Multiple paragraphs:
+
+1.	Item 1, graf one.
+
+	Item 2. graf two. The quick brown fox jumped over the lazy dog's
+	back.
+	
+2.	Item 2.
+
+3.	Item 3.
+
+
+
+## Nested
+
+*	Tab
+	*	Tab
+		*	Tab
+
+Here's another:
+
+1. First
+2. Second:
+	* Fee
+	* Fie
+	* Foe
+3. Third
+
+Same thing but with paragraphs:
+
+1. First
+
+2. Second:
+	* Fee
+	* Fie
+	* Foe
+
+3. Third
diff --git a/examples/basic/strong-and-em-together.txt b/examples/basic/strong-and-em-together.txt
new file mode 100644
index 0000000..95ee690
--- /dev/null
+++ b/examples/basic/strong-and-em-together.txt
@@ -0,0 +1,7 @@
+***This is strong and em.***
+
+So is ***this*** word.
+
+___This is strong and em.___
+
+So is ___this___ word.
diff --git a/examples/basic/tabs.txt b/examples/basic/tabs.txt
new file mode 100644
index 0000000..589d113
--- /dev/null
+++ b/examples/basic/tabs.txt
@@ -0,0 +1,21 @@
++	this is a list item
+	indented with tabs
+
++   this is a list item
+    indented with spaces
+
+Code:
+
+	this code block is indented by one tab
+
+And:
+
+		this code block is indented by two tabs
+
+And:
+
+	+	this is an example list item
+		indented with tabs
+	
+	+   this is an example list item
+	    indented with spaces
diff --git a/examples/basic/tidyness.txt b/examples/basic/tidyness.txt
new file mode 100644
index 0000000..5f18b8d
--- /dev/null
+++ b/examples/basic/tidyness.txt
@@ -0,0 +1,5 @@
+> A list within a blockquote:
+> 
+> *	asterisk 1
+> *	asterisk 2
+> *	asterisk 3
diff --git a/examples/basic_example.rs b/examples/basic_example.rs
new file mode 100644
index 0000000..873e2b3
--- /dev/null
+++ b/examples/basic_example.rs
@@ -0,0 +1,44 @@
+//! # Basic Example: HTML Generator
+//!
+//! This example demonstrates the fundamental functionality of the `html-generator` library,
+//! converting simple Markdown input into optimised HTML output using the default configuration.
+//!
+//! ## Features Highlighted
+//! - Basic Markdown to HTML conversion
+//! - Display of generated HTML output
+
+use html_generator::{generate_html, HtmlConfig};
+
+/// Entry point for the basic example of HTML Generator.
+///
+/// This example demonstrates the transformation of Markdown into HTML using the default
+/// configuration provided by the library.
+///
+/// # Errors
+/// Returns an error if the Markdown to HTML conversion fails.
+fn main() -> Result<(), Box> {
+    println!("\n🦀 Welcome to the Basic HTML Generator Example!");
+    println!("---------------------------------------------");
+
+    // Define simple Markdown content
+    let markdown = "# Welcome to HTML Generator\n\nEffortlessly convert Markdown into HTML.";
+
+    // Use the default HTML configuration
+    let config = HtmlConfig::default();
+
+    // Generate HTML from Markdown
+    let result = generate_html(markdown, &config);
+
+    match result {
+        Ok(html) => {
+            println!("    ✅ Successfully generated HTML:\n{}", html);
+        }
+        Err(e) => {
+            println!("    ❌ Failed to generate HTML: {}", e);
+        }
+    }
+
+    println!("\n🎉 Basic HTML generation completed!");
+
+    Ok(())
+}
diff --git a/examples/comprehensive_example.rs b/examples/comprehensive_example.rs
new file mode 100644
index 0000000..06e9902
--- /dev/null
+++ b/examples/comprehensive_example.rs
@@ -0,0 +1,336 @@
+//! # Batch Processing Markdown to HTML Example
+//!
+//! This example showcases the functionality of the `html-generator` library by
+//! converting Markdown content from multiple sources into HTML.
+//!
+//! ## Features Highlighted
+//! - Processes Markdown from a variety of sources, including basic and extended features.
+//! - Displays the HTML output for each source.
+
+use html_generator::{generate_html, HtmlConfig};
+use std::collections::HashMap;
+
+/// Entry point for the batch processing Markdown to HTML example.
+///
+/// Demonstrates conversion of Markdown from multiple sources into HTML.
+///
+/// # Errors
+/// Returns an error if any Markdown to HTML conversion fails.
+fn main() -> Result<(), Box> {
+    println!("\n🦀 Welcome to the Batch Processing Markdown to HTML Example!");
+    println!("================================================================");
+
+    // Markdown sources from the `./basic` folder
+    let basic_sources: HashMap<&str, &str> = vec![
+        (
+            "📝 Amps and Angle Encoding",
+            include_str!("./basic/amps-and-angle-encoding.txt"),
+        ),
+        (
+            "🔗 Angle Links and Images",
+            include_str!("./basic/angle-links-and-img.txt"),
+        ),
+        ("🌐 Auto Links", include_str!("./basic/auto-links.txt")),
+        (
+            "🎯 Backlash Escapes",
+            include_str!("./basic/backlash-escapes.txt"),
+        ),
+        (
+            "📜 Blockquotes with Code Blocks",
+            include_str!("./basic/blockquotes-with-code-blocks.txt"),
+        ),
+        (
+            "💡 Code Syntax Highlighting",
+            include_str!("./basic/code_syntax_highlighting.txt"),
+        ),
+        (
+            "🔢 Code Block in List",
+            include_str!("./basic/codeblock-in-list.txt"),
+        ),
+        (
+            "📦 Custom Containers",
+            include_str!("./basic/custom_containers.txt"),
+        ),
+        ("🕵️‍♂️ Edge Cases", include_str!("./basic/edge_cases.txt")),
+        (
+            "😀 Emoji Content",
+            include_str!("./basic/emoji_content.txt"),
+        ),
+        (
+            "🚩 Escaped Characters",
+            include_str!("./basic/escaped_characters.txt"),
+        ),
+        (
+            "⏩ Hard Wrapped Lines",
+            include_str!("./basic/hard-wrapped.txt"),
+        ),
+        (
+            "⏤ Horizontal Rules",
+            include_str!("./basic/horizontal-rules.txt"),
+        ),
+        (
+            "📚 Large Markdown File",
+            include_str!("./basic/large_markdown.txt"),
+        ),
+        ("🔗 Inline Links", include_str!("./basic/links-inline.txt")),
+        (
+            "📖 Reference Links",
+            include_str!("./basic/links-reference.txt"),
+        ),
+        (
+            "🗨️ Literal Quotes",
+            include_str!("./basic/literal-quotes.txt"),
+        ),
+        (
+            "📚 Markdown Basics",
+            include_str!("./basic/markdown-documentation-basics.txt"),
+        ),
+        (
+            "📘 Markdown Syntax",
+            include_str!("./basic/markdown-syntax.txt"),
+        ),
+        (
+            "🗨️ Nested Blockquotes",
+            include_str!("./basic/nested-blockquotes.txt"),
+        ),
+        (
+            "🔢 Ordered and Unordered Lists",
+            include_str!("./basic/ordered-and-unordered-list.txt"),
+        ),
+        (
+            "💪 Strong and Emphasis Together",
+            include_str!("./basic/strong-and-em-together.txt"),
+        ),
+        ("🗂️ Tabs", include_str!("./basic/tabs.txt")),
+        ("🧹 Tidiness", include_str!("./basic/tidyness.txt")),
+    ]
+    .into_iter()
+    .collect();
+
+    // Markdown sources from the `./extensions` folder
+    let extensions_sources: HashMap<&str, &str> = vec![
+        ("📘 Admonition", include_str!("./extensions/admonition.txt")),
+        (
+            "⚙️ Attribute List",
+            include_str!("./extensions/attr_list.txt"),
+        ),
+        ("✨ Codehilite", include_str!("./extensions/codehilite.txt")),
+        (
+            "🐙 GitHub Flavored Markdown",
+            include_str!("./extensions/github_flavored.txt"),
+        ),
+        (
+            "🌟 NL2BR with Attribute List",
+            include_str!("./extensions/nl2br_w_attr_list.txt"),
+        ),
+        ("📋 Sane Lists", include_str!("./extensions/sane_lists.txt")),
+        (
+            "🗂️ Table of Contents (TOC)",
+            include_str!("./extensions/toc.txt"),
+        ),
+        (
+            "🚨 TOC Invalid",
+            include_str!("./extensions/toc_invalid.txt"),
+        ),
+        (
+            "📄 TOC Nested List",
+            include_str!("./extensions/toc_nested_list.txt"),
+        ),
+        ("📂 TOC Nested", include_str!("./extensions/toc_nested.txt")),
+    ]
+    .into_iter()
+    .collect();
+
+    // Markdown sources from the `./misc` folder
+    let misc_sources: HashMap<&str, &str> = vec![
+        (
+            "⚙️ CRLF Line Ends",
+            include_str!("./misc/CRLF_line_ends.txt"),
+        ),
+        (
+            "🔗 Adjacent Headers",
+            include_str!("./misc/adjacent-headers.txt"),
+        ),
+        ("🌍 Arabic", include_str!("./misc/arabic.txt")),
+        (
+            "🔗 Autolinks with Asterisks",
+            include_str!("./misc/autolinks_with_asterisks.txt"),
+        ),
+        (
+            "🇷🇺 Autolinks with Asterisks (Russian)",
+            include_str!("./misc/autolinks_with_asterisks_russian.txt"),
+        ),
+        (
+            "🏷️ Backtick Escape",
+            include_str!("./misc/backtick-escape.txt"),
+        ),
+        ("🔄 Bidi", include_str!("./misc/bidi.txt")),
+        (
+            "📜 Blank Block Quote",
+            include_str!("./misc/blank-block-quote.txt"),
+        ),
+        (
+            "🔲 Blank Lines in Codeblocks",
+            include_str!("./misc/blank_lines_in_codeblocks.txt"),
+        ),
+        (
+            "🖋️ Blockquote Below Paragraph",
+            include_str!("./misc/blockquote-below-paragraph.txt"),
+        ),
+        (
+            "⏤ Blockquote Horizontal Rule",
+            include_str!("./misc/blockquote-hr.txt"),
+        ),
+        ("🗨️ Blockquote", include_str!("./misc/blockquote.txt")),
+        ("🔗 Bold Links", include_str!("./misc/bold_links.txt")),
+        ("⏎ Line Break", include_str!("./misc/br.txt")),
+        (
+            "🔎 Bracket Regular Expression",
+            include_str!("./misc/bracket_re.txt"),
+        ),
+        (
+            "🖼️ Brackets in Image Title",
+            include_str!("./misc/brackets-in-img-title.txt"),
+        ),
+        (
+            "🖋️ Code First Line",
+            include_str!("./misc/code-first-line.txt"),
+        ),
+        (
+            "🔗 Emphasis Around Links",
+            include_str!("./misc/em-around-links.txt"),
+        ),
+        (
+            "💪 Emphasis and Strong",
+            include_str!("./misc/em_strong.txt"),
+        ),
+        (
+            "💡 Complex Emphasis and Strong",
+            include_str!("./misc/em_strong_complex.txt"),
+        ),
+        ("📧 Email", include_str!("./misc/email.txt")),
+        ("🔗 Escaped Links", include_str!("./misc/escaped_links.txt")),
+        ("📋 Funky List", include_str!("./misc/funky-list.txt")),
+        ("#️⃣ H1", include_str!("./misc/h1.txt")),
+        ("#️⃣ Hash", include_str!("./misc/hash.txt")),
+        (
+            "🗂️ Header in Lists",
+            include_str!("./misc/header-in-lists.txt"),
+        ),
+        ("#️⃣ Headers", include_str!("./misc/headers.txt")),
+        ("⏤ Horizontal Line", include_str!("./misc/hline.txt")),
+        ("🖼️ Image 2", include_str!("./misc/image-2.txt")),
+        (
+            "🔗 Image in Links",
+            include_str!("./misc/image_in_links.txt"),
+        ),
+        (
+            "✏️ Insert at Start of Paragraph",
+            include_str!("./misc/ins-at-start-of-paragraph.txt"),
+        ),
+        ("📄 Inside HTML", include_str!("./misc/inside_html.txt")),
+        ("🇯🇵 Japanese", include_str!("./misc/japanese.txt")),
+        (
+            "🗨️ Lazy Blockquote",
+            include_str!("./misc/lazy-block-quote.txt"),
+        ),
+        (
+            "🔗 Link with Parenthesis",
+            include_str!("./misc/link-with-parenthesis.txt"),
+        ),
+        ("🗂️ Lists", include_str!("./misc/lists.txt")),
+        ("🗂️ Lists 2", include_str!("./misc/lists2.txt")),
+        ("🗂️ Lists 3", include_str!("./misc/lists3.txt")),
+        ("🗂️ Lists 4", include_str!("./misc/lists4.txt")),
+        ("🗂️ Lists 5", include_str!("./misc/lists5.txt")),
+        ("🗂️ Lists 6", include_str!("./misc/lists6.txt")),
+        ("🗂️ Lists 7", include_str!("./misc/lists7.txt")),
+        ("🗂️ Lists 8", include_str!("./misc/lists8.txt")),
+        (
+            "🔗 Missing Link Definition",
+            include_str!("./misc/missing-link-def.txt"),
+        ),
+        (
+            "🗨️ Multi-paragraph Blockquote",
+            include_str!("./misc/multi-paragraph-block-quote.txt"),
+        ),
+        ("🧪 Multi Test", include_str!("./misc/multi-test.txt")),
+        ("🗂️ Nested Lists", include_str!("./misc/nested-lists.txt")),
+        (
+            "🔍 Nested Patterns",
+            include_str!("./misc/nested-patterns.txt"),
+        ),
+        ("🛠️ Normalize", include_str!("./misc/normalize.txt")),
+        (
+            "#️⃣ Numeric Entity",
+            include_str!("./misc/numeric-entity.txt"),
+        ),
+        (
+            "🖋️ Paragraph with Horizontal Rule",
+            include_str!("./misc/para-with-hr.txt"),
+        ),
+        ("🇷🇺 Russian", include_str!("./misc/russian.txt")),
+        ("💡 Smart Emphasis", include_str!("./misc/smart_em.txt")),
+        ("🧪 Some Test", include_str!("./misc/some-test.txt")),
+        ("🖋️ Span", include_str!("./misc/span.txt")),
+        (
+            "💪 Strong with Underscores",
+            include_str!("./misc/strong-with-underscores.txt"),
+        ),
+        ("💪 Strong in Tags", include_str!("./misc/stronintags.txt")),
+        ("🔢 Tabs in Lists", include_str!("./misc/tabs-in-lists.txt")),
+        ("⏩ Two Spaces", include_str!("./misc/two-spaces.txt")),
+        ("💡 Uche", include_str!("./misc/uche.txt")),
+        ("🔗 Underscores", include_str!("./misc/underscores.txt")),
+        ("🌐 URL with Spaces", include_str!("./misc/url_spaces.txt")),
+    ]
+    .into_iter()
+    .collect();
+
+    // Process each group of sources
+    println!("\n📂 Processing Markdown from the `./basic` folder");
+    process_sources("📄 Basic Features", basic_sources)?;
+
+    println!("\n📂 Processing Markdown from the `./extensions` folder");
+    process_sources("🧩 Extended Features", extensions_sources)?;
+
+    println!("\n📂 Processing Markdown from the `./misc` folder");
+    process_sources("🔍 Miscellaneous Features", misc_sources)?;
+
+    println!("\n🎉 Batch processing example completed successfully!");
+
+    Ok(())
+}
+
+/// Processes a group of Markdown sources and generates HTML for each.
+fn process_sources(
+    group_name: &str,
+    sources: HashMap<&str, &str>,
+) -> Result<(), Box> {
+    println!("\n🗂️ Group: {group_name}");
+    println!(
+        "----------------------------------------------------------"
+    );
+
+    let config = HtmlConfig::default();
+
+    for (title, markdown) in sources {
+        println!("\n📝 Processing: {title}");
+        println!("----------------------------------------------------------");
+
+        // Generate HTML from Markdown
+        match generate_html(markdown, &config) {
+            Ok(html) => {
+                println!(
+                    "    ✅ Successfully generated HTML:\n{}",
+                    html
+                );
+            }
+            Err(e) => {
+                println!("    ❌ Failed to generate HTML: {}", e);
+            }
+        }
+    }
+
+    Ok(())
+}
diff --git a/examples/custom_config_example.rs b/examples/custom_config_example.rs
new file mode 100644
index 0000000..e926504
--- /dev/null
+++ b/examples/custom_config_example.rs
@@ -0,0 +1,39 @@
+// src/examples/custom_config_example.rs
+#![allow(missing_docs)]
+
+use html_generator::{generate_html, HtmlConfig, Result as HtmlResult};
+
+/// Demonstrates the use of a custom configuration for HTML generation.
+fn main() -> HtmlResult<()> {
+    println!(
+        "
+🧪 Custom Configuration Example
+"
+    );
+    println!("---------------------------------------------");
+
+    // Markdown content
+    let markdown = r#"# Custom Configuration
+This demonstrates a custom configuration for HTML generation."#;
+
+    // Customise the HTML configuration
+    let config = HtmlConfig::builder()
+        .with_language("en-GB")
+        .with_syntax_highlighting(true, Some("monokai".to_string()))
+        .build()?;
+
+    // Generate HTML with custom configuration
+    let html = generate_html(markdown, &config)?;
+    println!(
+        "    ✅ Generated HTML with custom configuration:
+{}",
+        html
+    );
+
+    println!(
+        "
+🎉 Custom configuration example completed successfully!"
+    );
+
+    Ok(())
+}
diff --git a/examples/extensions/admonition.txt b/examples/extensions/admonition.txt
new file mode 100644
index 0000000..03ff4e9
--- /dev/null
+++ b/examples/extensions/admonition.txt
@@ -0,0 +1,45 @@
+Some text
+
+!!! note
+    A normal paragraph here
+
+    1. first
+    2. second
+
+    > Some important quote
+
+    > another paragraph in the quote
+
+        int main() {
+            // insert some code
+        }
+
+More text and stuff.
+
+!!! Note "Did you know?"
+    You can customize the title of the admonition
+Not part of an Admonition!
+
+!!! mycustomcssclass "And now..."
+    For something completely different.
+
+    You can also use a custom CSS class name.
+
+!!! class1 class2    class3 "And now..."
+    For something completely different.
+
+    Several class names can be separated by space chars.
+
+!!! note anotherclass
+    The default title is the capitalized first class name.
+
+!!! tip ""
+    An explicitly empty string prevents the title from being rendered.
+
+No body:
+
+!!! note
+
+Extra whitespace after the title should not alter output:
+
+!!! note             
diff --git a/examples/extensions/attr_list.txt b/examples/extensions/attr_list.txt
new file mode 100644
index 0000000..465ce4f
--- /dev/null
+++ b/examples/extensions/attr_list.txt
@@ -0,0 +1,94 @@
+This is a sextext header {: #setext}
+====================================
+
+A paragraph with some text.
+Line two of the paragraph.
+{: #par1 .myclass }
+
+This is another {: #sextext2 .someclass}
+----------------------------------------
+
+Test some _inline_{: .inline} text.
+A [link](http://example.com){: .linkkyclass title="A title."}
+And a __nested [link][]{: .linky2}__{: .nest}
+
+[link]: http://example.com "Some title"
+
+### This is a hash Header ### {: #hash}
+
+And now some random attributes.
+{:foo bar='b az' baz="blah blah" title="I wasn't kidding!" }
+
+### No closing hash header {: #hash2}
+
+Now test overrides
+{: #overrideme .andme id=overridden class='foo bar' .addme }
+
+    # A code block which contains attr_list syntax
+    # This should be ignored.
+    {: #someid .someclass }
+
+### No colon for compatibility with Headerid ext { #hash3 }
+
+Also a codespan: `{: .someclass}`{: .foo}.
+{: #the_end}
+
+### Bad Syntax { {: #hash5 }
+
+* Item1
+  {: .item }
+* Item2
+  {: .item }
+    * Item2-1
+      {: .subitem }
+* _Item3_{: .emph }
+  {: .item }
+    * _Item3-1_{: .emph }
+      {: .subitem }
+* Item4
+    * Item4-1
+* Item5
+
+# And ordered lists *too*{.inline}
+
+1. Item1
+   {: .item }
+2. Item2
+   {: .item }
+    1. Item2-1
+       {: .subitem }
+3. _Item3_{: .emph }
+   {: .item }
+    1. _Item3-1_{: .emph }
+       {: .subitem }
+4. Item4
+    1. Item4-1
+5. Item5
+
+# Definition *lists* {.block}
+
+DT1 {.term}
+DT2 {.term}
+:   Some dd
+    {.def}
+:   *dd*{.inline}
+
+*DT3*{.inline}
+:   Some dd
+
+# Bad attributes
+
+Key without *value*{ foo= }
+
+Value without *key*{ =bar }
+
+No *key or value*{ = }
+
+*Weirdness*{ == }
+
+*More weirdness*{ === }
+
+This should not cause a *crash*{ foo=a=b }
+
+Attr_lists do not contain *newlines*{ foo=bar
+key=value }
diff --git a/examples/extensions/codehilite.txt b/examples/extensions/codehilite.txt
new file mode 100644
index 0000000..6c62e6a
--- /dev/null
+++ b/examples/extensions/codehilite.txt
@@ -0,0 +1,12 @@
+
+Some text
+
+    #!python
+    def __init__ (self, pattern) :
+        self.pattern = pattern
+        self.compiled_re = re.compile("^(.*)%s(.*)$" % pattern, re.DOTALL)
+
+    def getCompiledRegExp (self) :
+        return self.compiled_re
+
+More text
\ No newline at end of file
diff --git a/examples/extensions/github_flavored.txt b/examples/extensions/github_flavored.txt
new file mode 100644
index 0000000..4f362b7
--- /dev/null
+++ b/examples/extensions/github_flavored.txt
@@ -0,0 +1,45 @@
+index 0000000..6e956a9
+
+```diff
+--- /dev/null
++++ b/test/data/stripped_text/mike-30-lili
+@@ -0,0 +1,27 @@
++Summary:
++ drift_mod.py |    1 +
++ 1 files changed, 1 insertions(+), 0 deletions(-)
++
++commit da4bfb04debdd994683740878d09988b2641513d
++Author: Mike Dirolf 
++Date:   Tue Jan 17 13:42:28 2012 -0500
++
++```
++minor: just wanted to push something.
++```
++
++diff --git a/drift_mod.py b/drift_mod.py
++index 34dfba6..8a88a69 100644
++
++```
++--- a/drift_mod.py
+++++ b/drift_mod.py
++@@ -281,6 +281,7 @@ CONTEXT_DIFF_LINE_PATTERN = re.compile(r'^('
++                                        '|\+ .*'
++                                        '|- .*'
++                                        ')$')
+++
++ def wrap_context_diffs(message_text):
++     return _wrap_diff(CONTEXT_DIFF_HEADER_PATTERN,
++                       CONTEXT_DIFF_LINE_PATTERN,
++```
+```
+
+Test support for foo+bar lexer names.
+
+```html+jinja
+{% block title %}{% endblock %}
+
+```
diff --git a/examples/extensions/nl2br_w_attr_list.txt b/examples/extensions/nl2br_w_attr_list.txt
new file mode 100644
index 0000000..4b520b5
--- /dev/null
+++ b/examples/extensions/nl2br_w_attr_list.txt
@@ -0,0 +1,2 @@
+Foo
+{: #bar}
\ No newline at end of file
diff --git a/examples/extensions/sane_lists.txt b/examples/extensions/sane_lists.txt
new file mode 100644
index 0000000..464149f
--- /dev/null
+++ b/examples/extensions/sane_lists.txt
@@ -0,0 +1,26 @@
+1. Ordered
+2. List
+
+* Unordered
+* List
+
+1. Ordered again
+
+Paragraph
+* not a list item
+
+1. More ordered
+* not a list item
+
+* Unordered again
+1. not a list item
+
+3. Bird
+1. McHale
+8. Parish
+
+Not a list
+
+3. Bird
+1. McHale
+8. Parish
\ No newline at end of file
diff --git a/examples/extensions/toc.txt b/examples/extensions/toc.txt
new file mode 100644
index 0000000..1a1de34
--- /dev/null
+++ b/examples/extensions/toc.txt
@@ -0,0 +1,851 @@
+
+[TOC]
+
+# Overview
+
+## Philosophy
+
+Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
+
+Readability, however, is emphasized above all else. A Markdown-formatted
+document should be publishable as-is, as plain text, without looking
+like it's been marked up with tags or formatting instructions. While
+Markdown's syntax has been influenced by several existing text-to-HTML
+filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
+[Grutatext] [5], and [EtText] [6] -- the single biggest source of
+inspiration for Markdown's syntax is the format of plain text email.
+
+  [1]: http://docutils.sourceforge.net/mirror/setext.html
+  [2]: http://www.aaronsw.com/2002/atx/
+  [3]: http://textism.com/tools/textile/
+  [4]: http://docutils.sourceforge.net/rst.html
+  [5]: http://www.triptico.com/software/grutatxt.html
+  [6]: http://ettext.taint.org/doc/
+
+To this end, Markdown's syntax is comprised entirely of punctuation
+characters, which punctuation characters have been carefully chosen so
+as to look like what they mean. E.g., asterisks around a word actually
+look like \*emphasis\*. Markdown lists look like, well, lists. Even
+blockquotes look like quoted passages of text, assuming you've ever
+used email.
+
+
+
+## Inline HTML
+
+Markdown's syntax is intended for one purpose: to be used as a
+format for *writing* for the web.
+
+Markdown is not a replacement for HTML, or even close to it. Its
+syntax is very small, corresponding only to a very small subset of
+HTML tags. The idea is *not* to create a syntax that makes it easier
+to insert HTML tags. In my opinion, HTML tags are already easy to
+insert. The idea for Markdown is to make it easy to read, write, and
+edit prose. HTML is a *publishing* format; Markdown is a *writing*
+format. Thus, Markdown's formatting syntax only addresses issues that
+can be conveyed in plain text.
+
+For any markup that is not covered by Markdown's syntax, you simply
+use HTML itself. There's no need to preface it or delimit it to
+indicate that you're switching from Markdown to HTML; you just use
+the tags.
+
+The only restrictions are that block-level HTML elements -- e.g. `
                `,
+``, `
                `, `
                `, etc. -- must be separated from surrounding
+content by blank lines, and the start and end tags of the block should
+not be indented with tabs or spaces. Markdown is smart enough not
+to add extra (unwanted) `
                ` tags around HTML block-level tags.
+
+For example, to add an HTML table to a Markdown article:
+
+    This is a regular paragraph.
+
+    
                
+        
+            
+        
+    
                Foo
                
+
+    This is another regular paragraph.
+
+Note that Markdown formatting syntax is not processed within block-level
+HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
+HTML block.
+
+Span-level HTML tags -- e.g. ``, ``, or `` -- can be
+used anywhere in a Markdown paragraph, list item, or header. If you
+want, you can even use HTML tags instead of Markdown formatting; e.g. if
+you'd prefer to use HTML `` or `` tags instead of Markdown's
+link or image syntax, go right ahead.
+
+Unlike block-level HTML tags, Markdown syntax *is* processed within
+span-level tags.
+
+
+## Automatic Escaping for Special Characters
+
+In HTML, there are two characters that demand special treatment: `<`
+and `&`. Left angle brackets are used to start tags; ampersands are
+used to denote HTML entities. If you want to use them as literal
+characters, you must escape them as entities, e.g. `<`, and
+`&`.
+
+Ampersands in particular are bedeviling for web writers. If you want to
+write about 'AT&T', you need to write '`AT&T`'. You even need to
+escape ampersands within URLs. Thus, if you want to link to:
+
+    http://images.google.com/images?num=30&q=larry+bird
+
+you need to encode the URL as:
+
+    http://images.google.com/images?num=30&q=larry+bird
+
+in your anchor tag `href` attribute. Needless to say, this is easy to
+forget, and is probably the single most common source of HTML validation
+errors in otherwise well-marked-up web sites.
+
+Markdown allows you to use these characters naturally, taking care of
+all the necessary escaping for you. If you use an ampersand as part of
+an HTML entity, it remains unchanged; otherwise it will be translated
+into `&`.
+
+So, if you want to include a copyright symbol in your article, you can write:
+
+    ©
+
+and Markdown will leave it alone. But if you write:
+
+    AT&T
+
+Markdown will translate it to:
+
+    AT&T
+
+Similarly, because Markdown supports [inline HTML](#html), if you use
+angle brackets as delimiters for HTML tags, Markdown will treat them as
+such. But if you write:
+
+    4 < 5
+
+Markdown will translate it to:
+
+    4 < 5
+
+However, inside Markdown code spans and blocks, angle brackets and
+ampersands are *always* encoded automatically. This makes it easy to use
+Markdown to write about HTML code. (As opposed to raw HTML, which is a
+terrible format for writing about HTML syntax, because every single `<`
+and `&` in your example code needs to be escaped.)
+
+
+* * *
+
+
+# Block Elements
+
+
+## Paragraphs and Line Breaks
+
+A paragraph is simply one or more consecutive lines of text, separated
+by one or more blank lines. (A blank line is any line that looks like a
+blank line -- a line containing nothing but spaces or tabs is considered
+blank.) Normal paragraphs should not be indented with spaces or tabs.
+
+The implication of the "one or more consecutive lines of text" rule is
+that Markdown supports "hard-wrapped" text paragraphs. This differs
+significantly from most other text-to-HTML formatters (including Movable
+Type's "Convert Line Breaks" option) which translate every line break
+character in a paragraph into a `
                ` tag.
+
+When you *do* want to insert a `
                ` break tag using Markdown, you
+end a line with two or more spaces, then type return.
+
+Yes, this takes a tad more effort to create a `
                `, but a simplistic
+"every line break is a `
                `" rule wouldn't work for Markdown.
+Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
+work best -- and look better -- when you format them with hard breaks.
+
+  [bq]: #blockquote
+  [l]:  #list
+
+
+
+## Headers
+
+Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
+
+Setext-style headers are "underlined" using equal signs (for first-level
+headers) and dashes (for second-level headers). For example:
+
+    This is an H1
+    =============
+
+    This is an H2
+    -------------
+
+Any number of underlining `=`'s or `-`'s will work.
+
+Atx-style headers use 1-6 hash characters at the start of the line,
+corresponding to header levels 1-6. For example:
+
+    # This is an H1
+
+    ## This is an H2
+
+    ###### This is an H6
+
+Optionally, you may "close" atx-style headers. This is purely
+cosmetic -- you can use this if you think it looks better. The
+closing hashes don't even need to match the number of hashes
+used to open the header. (The number of opening hashes
+determines the header level.) :
+
+    # This is an H1 #
+
+    ## This is an H2 ##
+
+    ### This is an H3 ######
+
+
+## Blockquotes
+
+Markdown uses email-style `>` characters for blockquoting. If you're
+familiar with quoting passages of text in an email message, then you
+know how to create a blockquote in Markdown. It looks best if you hard
+wrap the text and put a `>` before every line:
+
+    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+    > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+    > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+    > 
+    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+    > id sem consectetuer libero luctus adipiscing.
+
+Markdown allows you to be lazy and only put the `>` before the first
+line of a hard-wrapped paragraph:
+
+    > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
+    consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
+    Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
+
+    > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
+    id sem consectetuer libero luctus adipiscing.
+
+Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
+adding additional levels of `>`:
+
+    > This is the first level of quoting.
+    >
+    > > This is nested blockquote.
+    >
+    > Back to the first level.
+
+Blockquotes can contain other Markdown elements, including headers, lists,
+and code blocks:
+
+	> ## This is a header.
+	> 
+	> 1.   This is the first list item.
+	> 2.   This is the second list item.
+	> 
+	> Here's some example code:
+	> 
+	>     return shell_exec("echo $input | $markdown_script");
+
+Any decent text editor should make email-style quoting easy. For
+example, with BBEdit, you can make a selection and choose Increase
+Quote Level from the Text menu.
+
+
+## Lists
+
+Markdown supports ordered (numbered) and unordered (bulleted) lists.
+
+Unordered lists use asterisks, pluses, and hyphens -- interchangeably
+-- as list markers:
+
+    *   Red
+    *   Green
+    *   Blue
+
+is equivalent to:
+
+    +   Red
+    +   Green
+    +   Blue
+
+and:
+
+    -   Red
+    -   Green
+    -   Blue
+
+Ordered lists use numbers followed by periods:
+
+    1.  Bird
+    2.  McHale
+    3.  Parish
+
+It's important to note that the actual numbers you use to mark the
+list have no effect on the HTML output Markdown produces. The HTML
+Markdown produces from the above list is:
+
+    
                  
+    
                1. Bird
                  2. 
+    
                2. McHale
                  3. 
+    
                3. Parish
                  4. 
+    
                
+
+If you instead wrote the list in Markdown like this:
+
+    1.  Bird
+    1.  McHale
+    1.  Parish
+
+or even:
+
+    3. Bird
+    1. McHale
+    8. Parish
+
+you'd get the exact same HTML output. The point is, if you want to,
+you can use ordinal numbers in your ordered Markdown lists, so that
+the numbers in your source match the numbers in your published HTML.
+But if you want to be lazy, you don't have to.
+
+If you do use lazy list numbering, however, you should still start the
+list with the number 1. At some point in the future, Markdown may support
+starting ordered lists at an arbitrary number.
+
+List markers typically start at the left margin, but may be indented by
+up to three spaces. List markers must be followed by one or more spaces
+or a tab.
+
+To make lists look nice, you can wrap items with hanging indents:
+
+    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+        Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+        viverra nec, fringilla in, laoreet vitae, risus.
+    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+        Suspendisse id sem consectetuer libero luctus adipiscing.
+
+But if you want to be lazy, you don't have to:
+
+    *   Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
+    Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
+    viverra nec, fringilla in, laoreet vitae, risus.
+    *   Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
+    Suspendisse id sem consectetuer libero luctus adipiscing.
+
+If list items are separated by blank lines, Markdown will wrap the
+items in `
                ` tags in the HTML output. For example, this input:
+
+    *   Bird
+    *   Magic
+
+will turn into:
+
+    
                  
+    
                • Bird
                  • 
+    
                • Magic
                  • 
+    
                
+
+But this:
+
+    *   Bird
+
+    *   Magic
+
+will turn into:
+
+    
                  
+    
                • Bird
                  • 
+    
                • Magic
                  • 
+    
                
+
+List items may consist of multiple paragraphs. Each subsequent
+paragraph in a list item must be indented by either 4 spaces
+or one tab:
+
+    1.  This is a list item with two paragraphs. Lorem ipsum dolor
+        sit amet, consectetuer adipiscing elit. Aliquam hendrerit
+        mi posuere lectus.
+
+        Vestibulum enim wisi, viverra nec, fringilla in, laoreet
+        vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
+        sit amet velit.
+
+    2.  Suspendisse id sem consectetuer libero luctus adipiscing.
+
+It looks nice if you indent every line of the subsequent
+paragraphs, but here again, Markdown will allow you to be
+lazy:
+
+    *   This is a list item with two paragraphs.
+
+        This is the second paragraph in the list item. You're
+    only required to indent the first line. Lorem ipsum dolor
+    sit amet, consectetuer adipiscing elit.
+
+    *   Another item in the same list.
+
+To put a blockquote within a list item, the blockquote's `>`
+delimiters need to be indented:
+
+    *   A list item with a blockquote:
+
+        > This is a blockquote
+        > inside a list item.
+
+To put a code block within a list item, the code block needs
+to be indented *twice* -- 8 spaces or two tabs:
+
+    *   A list item with a code block:
+
+            
+
+
+It's worth noting that it's possible to trigger an ordered list by
+accident, by writing something like this:
+
+    1986. What a great season.
+
+In other words, a *number-period-space* sequence at the beginning of a
+line. To avoid this, you can backslash-escape the period:
+
+    1986\. What a great season.
+
+
+
+## Code Blocks
+
+Pre-formatted code blocks are used for writing about programming or
+markup source code. Rather than forming normal paragraphs, the lines
+of a code block are interpreted literally. Markdown wraps a code block
+in both `
                ` and `` tags.
+
+To produce a code block in Markdown, simply indent every line of the
+block by at least 4 spaces or 1 tab. For example, given this input:
+
+    This is a normal paragraph:
+
+        This is a code block.
+
+Markdown will generate:
+
+    
                This is a normal paragraph:
                
+
+    
                This is a code block.
+    
                
+
+One level of indentation -- 4 spaces or 1 tab -- is removed from each
+line of the code block. For example, this:
+
+    Here is an example of AppleScript:
+
+        tell application "Foo"
+            beep
+        end tell
+
+will turn into:
+
+    
                Here is an example of AppleScript:
                
+
+    
                tell application "Foo"
+        beep
+    end tell
+    
                
+
+A code block continues until it reaches a line that is not indented
+(or the end of the article).
+
+Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
+are automatically converted into HTML entities. This makes it very
+easy to include example HTML source code using Markdown -- just paste
+it and indent it, and Markdown will handle the hassle of encoding the
+ampersands and angle brackets. For example, this:
+
+        
                
+            © 2004 Foo Corporation
+        
                
+
+will turn into:
+
+    
                <div class="footer">
+        &copy; 2004 Foo Corporation
+    </div>
+    
                
+
+Regular Markdown syntax is not processed within code blocks. E.g.,
+asterisks are just literal asterisks within a code block. This means
+it's also easy to use Markdown to write about Markdown's own syntax.
+
+
+
+## Horizontal Rules
+
+You can produce a horizontal rule tag (`
                `) by placing three or
+more hyphens, asterisks, or underscores on a line by themselves. If you
+wish, you may use spaces between the hyphens or asterisks. Each of the
+following lines will produce a horizontal rule:
+
+    * * *
+
+    ***
+
+    *****
+	
+    - - -
+
+    ---------------------------------------
+
+	_ _ _
+
+
+* * *
+
+# Span Elements
+
+## Links
+
+Markdown supports two style of links: *inline* and *reference*.
+
+In both styles, the link text is delimited by [square brackets].
+
+To create an inline link, use a set of regular parentheses immediately
+after the link text's closing square bracket. Inside the parentheses,
+put the URL where you want the link to point, along with an *optional*
+title for the link, surrounded in quotes. For example:
+
+    This is [an example](http://example.com/ "Title") inline link.
+
+    [This link](http://example.net/) has no title attribute.
+
+Will produce:
+
+    
                This is 
+    an example inline link.
                
+
+    
                This link has no
+    title attribute.
                
+
+If you're referring to a local resource on the same server, you can
+use relative paths:
+
+    See my [About](/about/) page for details.   
+
+Reference-style links use a second set of square brackets, inside
+which you place a label of your choosing to identify the link:
+
+    This is [an example][id] reference-style link.
+
+You can optionally use a space to separate the sets of brackets:
+
+    This is [an example] [id] reference-style link.
+
+Then, anywhere in the document, you define your link label like this,
+on a line by itself:
+
+    [id]: http://example.com/  "Optional Title Here"
+
+That is:
+
+*   Square brackets containing the link identifier (optionally
+    indented from the left margin using up to three spaces);
+*   followed by a colon;
+*   followed by one or more spaces (or tabs);
+*   followed by the URL for the link;
+*   optionally followed by a title attribute for the link, enclosed
+    in double or single quotes.
+
+The link URL may, optionally, be surrounded by angle brackets:
+
+    [id]:   "Optional Title Here"
+
+You can put the title attribute on the next line and use extra spaces
+or tabs for padding, which tends to look better with longer URLs:
+
+    [id]: http://example.com/longish/path/to/resource/here
+        "Optional Title Here"
+
+Link definitions are only used for creating links during Markdown
+processing, and are stripped from your document in the HTML output.
+
+Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
+
+	[link text][a]
+	[link text][A]
+
+are equivalent.
+
+The *implicit link name* shortcut allows you to omit the name of the
+link, in which case the link text itself is used as the name.
+Just use an empty set of square brackets -- e.g., to link the word
+"Google" to the google.com web site, you could simply write:
+
+	[Google][]
+
+And then define the link:
+
+	[Google]: http://google.com/
+
+Because link names may contain spaces, this shortcut even works for
+multiple words in the link text:
+
+	Visit [Daring Fireball][] for more information.
+
+And then define the link:
+	
+	[Daring Fireball]: http://daringfireball.net/
+
+Link definitions can be placed anywhere in your Markdown document. I
+tend to put them immediately after each paragraph in which they're
+used, but if you want, you can put them all at the end of your
+document, sort of like footnotes.
+
+Here's an example of reference links in action:
+
+    I get 10 times more traffic from [Google] [1] than from
+    [Yahoo] [2] or [MSN] [3].
+
+      [1]: http://google.com/        "Google"
+      [2]: http://search.yahoo.com/  "Yahoo Search"
+      [3]: http://search.msn.com/    "MSN Search"
+
+Using the implicit link name shortcut, you could instead write:
+
+    I get 10 times more traffic from [Google][] than from
+    [Yahoo][] or [MSN][].
+
+      [google]: http://google.com/        "Google"
+      [yahoo]:  http://search.yahoo.com/  "Yahoo Search"
+      [msn]:    http://search.msn.com/    "MSN Search"
+
+Both of the above examples will produce the following HTML output:
+
+    
                I get 10 times more traffic from Google than from
+    Yahoo
+    or MSN.
                
+
+For comparison, here is the same paragraph written using
+Markdown's inline link style:
+
+    I get 10 times more traffic from [Google](http://google.com/ "Google")
+    than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
+    [MSN](http://search.msn.com/ "MSN Search").
+
+The point of reference-style links is not that they're easier to
+write. The point is that with reference-style links, your document
+source is vastly more readable. Compare the above examples: using
+reference-style links, the paragraph itself is only 81 characters
+long; with inline-style links, it's 176 characters; and as raw HTML,
+it's 234 characters. In the raw HTML, there's more markup than there
+is text.
+
+With Markdown's reference-style links, a source document much more
+closely resembles the final output, as rendered in a browser. By
+allowing you to move the markup-related metadata out of the paragraph,
+you can add links without interrupting the narrative flow of your
+prose.
+
+
+## Emphasis
+
+Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
+emphasis. Text wrapped with one `*` or `_` will be wrapped with an
+HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML
+`` tag. E.g., this input:
+
+    *single asterisks*
+
+    _single underscores_
+
+    **double asterisks**
+
+    __double underscores__
+
+will produce:
+
+    single asterisks
+
+    single underscores
+
+    double asterisks
+
+    double underscores
+
+You can use whichever style you prefer; the lone restriction is that
+the same character must be used to open and close an emphasis span.
+
+Emphasis can be used in the middle of a word:
+
+    un*fucking*believable
+
+But if you surround an `*` or `_` with spaces, it'll be treated as a
+literal asterisk or underscore.
+
+To produce a literal asterisk or underscore at a position where it
+would otherwise be used as an emphasis delimiter, you can backslash
+escape it:
+
+    \*this text is surrounded by literal asterisks\*
+
+
+
+## Code
+
+To indicate a span of code, wrap it with backtick quotes (`` ` ``).
+Unlike a pre-formatted code block, a code span indicates code within a
+normal paragraph. For example:
+
+    Use the `printf()` function.
+
+will produce:
+
+    
                Use the printf() function.
                
+
+To include a literal backtick character within a code span, you can use
+multiple backticks as the opening and closing delimiters:
+
+    ``There is a literal backtick (`) here.``
+
+which will produce this:
+
+    
                There is a literal backtick (`) here.
                
+
+The backtick delimiters surrounding a code span may include spaces --
+one after the opening, one before the closing. This allows you to place
+literal backtick characters at the beginning or end of a code span:
+
+	A single backtick in a code span: `` ` ``
+	
+	A backtick-delimited string in a code span: `` `foo` ``
+
+will produce:
+
+	
                A single backtick in a code span: `
                
+	
+	
                A backtick-delimited string in a code span: `foo`
                
+
+With a code span, ampersands and angle brackets are encoded as HTML
+entities automatically, which makes it easy to include example HTML
+tags. Markdown will turn this:
+
+    Please don't use any `` tags.
+
+into:
+
+    
                Please don't use any <blink> tags.
                
+
+You can write this:
+
+    `—` is the decimal-encoded equivalent of `—`.
+
+to produce:
+
+    
                &#8212; is the decimal-encoded
+    equivalent of &mdash;.
                
+
+
+
+## Images
+
+Admittedly, it's fairly difficult to devise a "natural" syntax for
+placing images into a plain text document format.
+
+Markdown uses an image syntax that is intended to resemble the syntax
+for links, allowing for two styles: *inline* and *reference*.
+
+Inline image syntax looks like this:
+
+    ![Alt text](/path/to/img.jpg)
+
+    ![Alt text](/path/to/img.jpg "Optional title")
+
+That is:
+
+*   An exclamation mark: `!`;
+*   followed by a set of square brackets, containing the `alt`
+    attribute text for the image;
+*   followed by a set of parentheses, containing the URL or path to
+    the image, and an optional `title` attribute enclosed in double
+    or single quotes.
+
+Reference-style image syntax looks like this:
+
+    ![Alt text][id]
+
+Where "id" is the name of a defined image reference. Image references
+are defined using syntax identical to link references:
+
+    [id]: url/to/image  "Optional title attribute"
+
+As of this writing, Markdown has no syntax for specifying the
+dimensions of an image; if this is important to you, you can simply
+use regular HTML `` tags.
+
+
+* * *
+
+
+# Miscellaneous
+
+## Automatic Links
+
+Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
+
+    
+    
+Markdown will turn this into:
+
+    http://example.com/
+
+Automatic links for email addresses work similarly, except that
+Markdown will also perform a bit of randomized decimal and hex
+entity-encoding to help obscure your address from address-harvesting
+spambots. For example, Markdown will turn this:
+
+    
+
+into something like this:
+
+    address@exa
+    mple.com
+
+which will render in a browser as a clickable link to "address@example.com".
+
+(This sort of entity-encoding trick will indeed fool many, if not
+most, address-harvesting bots, but it definitely won't fool all of
+them. It's better than nothing, but an address published in this way
+will probably eventually start receiving spam.)
+
+
+
+## Backslash Escapes
+
+Markdown allows you to use backslash escapes to generate literal
+characters which would otherwise have special meaning in Markdown's
+formatting syntax. For example, if you wanted to surround a word with
+literal asterisks (instead of an HTML `` tag), you can backslashes
+before the asterisks, like this:
+
+    \*literal asterisks\*
+
+Markdown provides backslash escapes for the following characters:
+
+    \   backslash
+    `   backtick
+    *   asterisk
+    _   underscore
+    {}  curly braces
+    []  square brackets
+    ()  parentheses
+    #   hash mark
+	+	plus sign
+	-	minus sign (hyphen)
+    .   dot
+    !   exclamation mark
+
diff --git a/examples/extensions/toc_invalid.txt b/examples/extensions/toc_invalid.txt
new file mode 100644
index 0000000..f6c4ec4
--- /dev/null
+++ b/examples/extensions/toc_invalid.txt
@@ -0,0 +1,9 @@
+[TOC]
+-----
+
+# Header 1
+
+The TOC marker cannot be inside a header. This test makes sure markdown doesn't 
+crash when it encounters this  errant syntax. The unexpected output should
+clue the author in that s/he needs to add a blank line between the TOC and
+the `
                `.
diff --git a/examples/extensions/toc_nested.txt b/examples/extensions/toc_nested.txt
new file mode 100644
index 0000000..0f897b2
--- /dev/null
+++ b/examples/extensions/toc_nested.txt
@@ -0,0 +1,9 @@
+# Header A
+
+## Header 1
+
+### Header i
+
+# Header *B*
+
+[TOC]
diff --git a/examples/extensions/toc_nested2.txt b/examples/extensions/toc_nested2.txt
new file mode 100644
index 0000000..9db4d8c
--- /dev/null
+++ b/examples/extensions/toc_nested2.txt
@@ -0,0 +1,10 @@
+[TOC]
+
+### Start with header other than one.
+
+### Header 3
+
+#### Header 4
+
+### Header 3
+
diff --git a/examples/extensions/toc_nested_list.txt b/examples/extensions/toc_nested_list.txt
new file mode 100644
index 0000000..d83e96f
--- /dev/null
+++ b/examples/extensions/toc_nested_list.txt
@@ -0,0 +1,19 @@
+# Title
+
+[TOC]
+
+## Section 1
+
+1. List Item 1
+
+    ### Subsection 1
+    Explanation 1
+
+2. List Item 2
+
+    ### Subsection 2
+    Explanation 2
+
+## Section 2
+
+## Section 3
\ No newline at end of file
diff --git a/examples/extensions/toc_out_of_order.txt b/examples/extensions/toc_out_of_order.txt
new file mode 100644
index 0000000..f08bdbc
--- /dev/null
+++ b/examples/extensions/toc_out_of_order.txt
@@ -0,0 +1,5 @@
+[TOC]
+
+## Header 2
+
+# Header 1
diff --git a/examples/extensions/wikilinks.txt b/examples/extensions/wikilinks.txt
new file mode 100644
index 0000000..8e6911b
--- /dev/null
+++ b/examples/extensions/wikilinks.txt
@@ -0,0 +1,14 @@
+Some text with a [[WikiLink]].
+
+A link with [[ white space and_underscores ]] and a empty [[ ]] one.
+
+Another with [[double  spaces]] and [[double__underscores]] and 
+one that [[has _emphasis_ inside]] and one [[with_multiple_underscores]] 
+and one that is _[[emphasised]]_.
+
+And a RealLink.
+
+
+
+And a [MarkdownLink](/MarkdownLink/ "A MarkdownLink") for
+completeness.
diff --git a/examples/misc/CRLF_line_ends.txt b/examples/misc/CRLF_line_ends.txt
new file mode 100644
index 0000000..5528995
--- /dev/null
+++ b/examples/misc/CRLF_line_ends.txt
@@ -0,0 +1,5 @@
+foo
+
+
                
+bar
+
                
diff --git a/examples/misc/adjacent-headers.txt b/examples/misc/adjacent-headers.txt
new file mode 100644
index 0000000..0e626b9
--- /dev/null
+++ b/examples/misc/adjacent-headers.txt
@@ -0,0 +1,2 @@
+# this is a huge header #
+## this is a smaller header ##
diff --git a/examples/misc/arabic.txt b/examples/misc/arabic.txt
new file mode 100644
index 0000000..ba2fef4
--- /dev/null
+++ b/examples/misc/arabic.txt
@@ -0,0 +1,37 @@
+
+بايثون
+=====
+
+**بايثون** لغة برمجة حديثة بسيطة، واضحة، سريعة ، تستخدم أسلوب البرمجة الكائنية (OOP) وقابلة للتطوير بالإضافة إلى أنها مجانية و مفتوحة المصدر. صُنفت بالأساس كلغة تفسيرية ، بايثون مصممة أصلاً للأداء بعض المهام الخاصة أو المحدودة. إلا أنه يمكن استخدامها بايثون لإنجاز المشاريع الضخمه كأي لغة برمجية أخرى،  غالباً ما يُنصح المبتدئين في ميدان البرمجة بتعلم هذه اللغة لأنها من بين أسهل اللغات البرمجية تعلماً.
+
+نشأت بايثون في مركز CWI (مركز العلوم والحاسب الآلي) بأمستردام على يد جويدو فان رُزوم. تم تطويرها بلغة C. أطلق فان رُزوم اسم "بايثون" على لغته تعبيرًا عن إعجابه بفِرقَة مسرحية هزلية شهيرة من بريطانيا، كانت تطلق على نفسها اسم مونتي بايثون Monty Python.
+
+تتميز بايثون بمجتمعها النشط ، كما أن لها الكثير من المكتبات البرمجية ذات الأغراض الخاصة والتي برمجها أشخاص من مجتمع هذه اللغة ، مثلاً مكتبة PyGame التي توفر مجموعه من الوظائف من اجل برمجة الالعاب. ويمكن لبايثون التعامل مع العديد من أنواع قواعد البيانات مثل MySQL وغيره.
+
+##أمثلة 
+مثال Hello World!
+
+    print "Hello World!"
+
+
+مثال لاستخراج المضروب Factorial :
+
+    num = 1
+    x = raw_input('Insert the number please ')
+    x = int(x)
+ 
+    if x > 69:
+     print 'Math Error !'
+    else:
+     while x > 1:
+      num *= x
+      x = x-1
+ 
+     print num
+
+
+
+##وصلات خارجية 
+* [الموقع الرسمي للغة بايثون](http://www.python.org)
+
+ بذرة حاس 
diff --git a/examples/misc/autolinks_with_asterisks.txt b/examples/misc/autolinks_with_asterisks.txt
new file mode 100644
index 0000000..24de5d9
--- /dev/null
+++ b/examples/misc/autolinks_with_asterisks.txt
@@ -0,0 +1,2 @@
+
+
diff --git a/examples/misc/autolinks_with_asterisks_russian.txt b/examples/misc/autolinks_with_asterisks_russian.txt
new file mode 100644
index 0000000..74465f1
--- /dev/null
+++ b/examples/misc/autolinks_with_asterisks_russian.txt
@@ -0,0 +1,3 @@
+
+
+
diff --git a/examples/misc/backtick-escape.txt b/examples/misc/backtick-escape.txt
new file mode 100644
index 0000000..c019463
--- /dev/null
+++ b/examples/misc/backtick-escape.txt
@@ -0,0 +1,4 @@
+\`This should not be in code.\`
+\\`This should be in code.\\`
+\\\`This should not be in code.\\\`
+\`And finally this should not be in code.`
diff --git a/examples/misc/bidi.txt b/examples/misc/bidi.txt
new file mode 100644
index 0000000..7e6dbea
--- /dev/null
+++ b/examples/misc/bidi.txt
@@ -0,0 +1,68 @@
+**Python**（パイソン）は、[Guido van Rossum](http://en.wikipedia.org/wiki/Guido_van_Rossum) によって作られたオープンソースのオブジェクト指向スクリプト言語。[Perl](http://ja.wikipedia.org/wiki/Perl)とともに欧米で広く普及している。イギリスのテレビ局 BBC が製作したコメディ番組『空飛ぶモンティ・パイソン』にちなんで名付けられた。 (Pythonには、爬虫類のニシキヘビの意味があり、Python言語のマスコットやアイコンとして使われることがある。)
+
+|||||||||||||||||||||||||||||THIS SHOULD BE LTR|||||||||||||||||||||||||
+
+|||||||||||||||||||||||||||||THIS SHOULD BE RTL|||||||||||||||||||||||||  
+
+
+(**بايثون** لغة برمجة حديثة بسيطة، واضحة، سريعة ، تستخدم أسلوب البرمجة الكائنية (THIS SHOULD BE LTR ) وقابلة للتطوير  بالإضافة إلى أنها مجانية و مفتوح 
+
+
+
+
+
+پایتون زبان برنامه‌نویسی تفسیری و سطح بالا ، شی‌گرا و یک زبان برنامه‌نویسی تفسیری سمت سرور قدرتمند است که توسط گیدو ون روسوم در سال ۱۹۹۰ ساخته شد. این زبان در ویژگی‌ها شبیه پرل، روبی، اسکیم، اسمال‌تاک و تی‌سی‌ال است و از مدیریت خودکار حافظه استفاده می‌کند
+
+Python，是一种面向对象的、直譯式的计算机程序设计语言，也是一种功能强大而完善的通用型语言，已经具有十多年的发展历史，成熟且稳定。
+
+ބްލޫ ވޭލްގެ ދޫ މަތީގައި އެއްފަހަރާ 50 މީހުންނަށް ތިބެވިދާނެވެ. ބޮޑު މަހުގެ ދުލަކީ އެހާމެ ބޮޑު އެއްޗެކެވެ.
+
+**உருது** 13ஆம் நூற்றாண்டில் உருவான ஒரு இந்தோ-ஐரோப்பிய மொழியாகும். உருது, ஹிந்தியுடன் சேர்த்து "ஹிந்துஸ்தானி" என அழைக்கப்படுகின்றது. மண்டரின், ஆங்கிலம் ஆகியவற்றுக்கு அடுத்தபடியாக மூன்றாவது கூடிய அளவு மக்களால் புரிந்து கொள்ளப்படக்கூடியது ஹிந்துஸ்தானியேயாகும். தாய் மொழியாகப் பேசுபவர்கள் எண்ணிக்கையின் அடிப்படையில் உருது உலகின் 20 ஆவது பெரிய மொழியாகும். 6 கோடி மக்கள் இதனைத் தாய் மொழியாகக் கொண்டுள்ளார்கள். இரண்டாவது மொழியாகக் கொண்டுள்ளவர்கள் உட்பட 11 கோடிப் பேர் இதனைப் பேசுகிறார்கள். உருது பாகிஸ்தானின் அரசகரும மொழியாகவும், இந்தியாவின் அரசகரும மொழிகளுள் ஒன்றாகவும் விளங்குகிறது.
+
+اردو ہندوآریائی زبانوں کی ہندويورپی شاخ کی ایک زبان ہے جو تيرھويں صدی ميں بر صغير ميں پيدا ہوئی ـ اردو پاکستان کی سرکاری زبان ہے اور بھارت کی سرکاری زبانوں ميں سے ايک ہے۔ اردو بھارت ميں 5 کروڑ اور پاکستان ميں 1 کروڑ لوگوں کی مادری زبان ہے مگر اسے بھارت اور پاکستان کے تقریباً 50 کروڑ لوگ بول اور سمجھ سکتے ھیں ۔ جن میں سے تقریباً 10.5 کروڑ لوگ اسے باقاعدہ بولتے ھیں۔
+
+بايثون
+=====
+
+**بايثون** لغة برمجة حديثة بسيطة، واضحة، سريعة ، تستخدم أسلوب البرمجة الكائنية (OOP) وقابلة للتطوير بالإضافة إلى أنها مجانية و مفتوحة المصدر. صُنفت بالأساس كلغة تفسيرية ، بايثون مصممة أصلاً للأداء بعض المهام الخاصة أو المحدودة. إلا أنه يمكن استخدامها بايثون لإنجاز المشاريع الضخمه كأي لغة برمجية أخرى،  غالباً ما يُنصح المبتدئين في ميدان البرمجة بتعلم هذه اللغة لأنها من بين أسهل اللغات البرمجية تعلماً.
+
+|||||||||||||||||||||||||||||THIS SHOULD BE RTL|||||||||||||||||||||||||
+
+(نشأت بايثون في مركز CWI (مركز العلوم والحاسب الآلي) بأمستردام على يد جويدو فان رُزوم. تم تطويرها بلغة C. أطلق فان رُزوم اسم "بايثون" على لغته تعبيرًا عن إعجابه بفِرقَة مسرحية هزلية شهيرة من بريطانيا، كانت تطلق على نفسها اسم مونتي بايثون Monty Python.
+
+تتميز بايثون بمجتمعها النشط ، كما أن لها الكثير من المكتبات البرمجية ذات الأغراض الخاصة والتي برمجها أشخاص من مجتمع هذه اللغة ، مثلاً مكتبة PyGame التي توفر مجموعه من الوظائف من اجل برمجة الالعاب. ويمكن لبايثون التعامل مع العديد من أنواع قواعد البيانات مثل MySQL وغيره.
+
+##أمثلة 
+مثال Hello World!
+
+    print "Hello World!"
+
+
+مثال لاستخراج المضروب Factorial :
+
+    num = 1
+    x = raw_input('Insert the number please ')
+    x = int(x)
+ 
+    if x > 69:
+     print 'Math Error !'
+    else:
+     while x > 1:
+      num *= x
+      x = x-1
+ 
+     print num
+
+
+
+##وصلات خارجية 
+* [الموقع الرسمي للغة بايثون](http://www.python.org)
+
+ بذرة حاس 
+
+
+**Недвард «Нед» Фландерс** (Nedward «Ned» Flanders) — вымышленный персонаж мультсериала «[Симпсоны][]», озвученный Гарри Ширером. Он и его семья живут по соседству от семьи Симпсонов. Набожный христианин, Нед является одним из столпов морали Спрингфилда. В эпизоде «Alone Again, Natura-Diddily»  он овдовел, его жена Мод погибла в результате несчастного случая. 
+
+Нед был одним из первых персонажей в мультсериале, который не был членом семьи Симпсонов. Начиная с первых серий, он регулярно появляется в «Симпсонах». Считается, что Нед Фландерс был назван в честь улицы *Northeast Flanders St.* в [Портленде](http://www.portland.gov), Орегон, родном городе создателя мультсериала Мэтта Грейнинга]]. Надпись на указателе улицы *NE Flanders St.* хулиганы часто исправляли на _NED Flanders St._
+
+
diff --git a/examples/misc/blank-block-quote.txt b/examples/misc/blank-block-quote.txt
new file mode 100644
index 0000000..75bfc74
--- /dev/null
+++ b/examples/misc/blank-block-quote.txt
@@ -0,0 +1,6 @@
+
+aaaaaaaaaaa
+
+> 
+
+bbbbbbbbbbb
diff --git a/examples/misc/blank_lines_in_codeblocks.txt b/examples/misc/blank_lines_in_codeblocks.txt
new file mode 100644
index 0000000..e7ae102
--- /dev/null
+++ b/examples/misc/blank_lines_in_codeblocks.txt
@@ -0,0 +1,73 @@
+Preserve blank lines in code blocks with tabs:
+
+    a code block
+    
+    two tabbed lines
+    
+    
+    three tabbed lines
+    
+    
+    
+    four tabbed lines
+    
+    
+    
+    
+    five tabbed lines
+    
+    
+    
+    
+    
+    six tabbed lines
+    
+    
+    
+    
+    
+    
+    End of tabbed block
+    
+    
+    
+    
+    
+    
+And without tabs:
+
+    a code block
+
+    two blank lines
+
+
+    three blank lines
+
+
+
+    four blank lines
+
+
+
+
+    five blank lines
+
+
+
+
+
+    six blank lines
+
+
+
+
+
+
+    End of block
+
+
+
+
+
+
+End of document
\ No newline at end of file
diff --git a/examples/misc/blockquote-below-paragraph.txt b/examples/misc/blockquote-below-paragraph.txt
new file mode 100644
index 0000000..529e5a9
--- /dev/null
+++ b/examples/misc/blockquote-below-paragraph.txt
@@ -0,0 +1,11 @@
+Paragraph
+> Block quote
+> Yep
+
+Paragraph
+>no space
+>Nope
+
+Paragraph one
+> blockquote
+More blockquote.
diff --git a/examples/misc/blockquote-hr.txt b/examples/misc/blockquote-hr.txt
new file mode 100644
index 0000000..8f67b24
--- /dev/null
+++ b/examples/misc/blockquote-hr.txt
@@ -0,0 +1,27 @@
+This is a paragraph.
+
+---
+
+> Block quote with horizontal lines.
+
+> ---
+
+> > Double block quote.
+
+> > ---
+
+> > End of the double block quote.
+
+> A new paragraph.
+> With multiple lines.
+Even a lazy line.
+
+> ---
+
+> The last line.
+
+foo
+> bar
+> ***
+---
+> baz
diff --git a/examples/misc/blockquote.txt b/examples/misc/blockquote.txt
new file mode 100644
index 0000000..be3ff90
--- /dev/null
+++ b/examples/misc/blockquote.txt
@@ -0,0 +1,21 @@
+> blockquote with no whitespace before `>`.
+
+foo
+
+ > blockquote with one space before the `>`.
+
+bar
+
+  > blockquote with 2 spaces.
+
+baz
+
+   > this has three spaces so its a paragraph.
+
+blah
+
+    > this one had four so it's a code block.
+
+>   > this nested blockquote has 0 on level one and 3 (one after the first `>` + 2 more) on level 2.
+
+>    > and this has 4 on level 2 - another code block.
diff --git a/examples/misc/bold_links.txt b/examples/misc/bold_links.txt
new file mode 100644
index 0000000..a07f441
--- /dev/null
+++ b/examples/misc/bold_links.txt
@@ -0,0 +1 @@
+**bold [link](http://example.com)**
diff --git a/examples/misc/br.txt b/examples/misc/br.txt
new file mode 100644
index 0000000..19f4cf1
--- /dev/null
+++ b/examples/misc/br.txt
@@ -0,0 +1,16 @@
+Output:
+
+    
                Some of these words are emphasized.
+    Some of these words are emphasized also.
                
+
+    
                Use two asterisks for strong emphasis.
+    Or, if you prefer, use two underscores instead.
                
+
+
+
+## Lists ##
+
+Unordered (bulleted) lists use asterisks, pluses, and hyphens (`*`,
+`+`, and `-`) as list markers. These three markers are
+interchangeable; this:
+
diff --git a/examples/misc/bracket_re.txt b/examples/misc/bracket_re.txt
new file mode 100644
index 0000000..545e061
--- /dev/null
+++ b/examples/misc/bracket_re.txt
@@ -0,0 +1,61 @@
+
+[x
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
+xxx xxx xxx xxx xxx xxx xxx xxx
diff --git a/examples/misc/brackets-in-img-title.txt b/examples/misc/brackets-in-img-title.txt
new file mode 100644
index 0000000..01fcd4e
--- /dev/null
+++ b/examples/misc/brackets-in-img-title.txt
@@ -0,0 +1,12 @@
+![alt](local-img.jpg)
+![alt](local-img.jpg "")
+![alt](local-img.jpg "normal title")
+
+![alt](local-img.jpg "(just title in brackets)")
+![alt](local-img.jpg "title with brackets (I think)")
+
+![alt](local-img.jpg "(")
+![alt](local-img.jpg "(open only")
+![alt](local-img.jpg ")")
+![alt](local-img.jpg "close only)")
+
diff --git a/examples/misc/code-first-line.txt b/examples/misc/code-first-line.txt
new file mode 100644
index 0000000..952614d
--- /dev/null
+++ b/examples/misc/code-first-line.txt
@@ -0,0 +1 @@
+    print "This is a code block."
diff --git a/examples/misc/em-around-links.txt b/examples/misc/em-around-links.txt
new file mode 100644
index 0000000..dbc3644
--- /dev/null
+++ b/examples/misc/em-around-links.txt
@@ -0,0 +1,14 @@
+# Title
+
+  - *[Python in Markdown](http://example.com) by some
+    great folks* - This *does* work as expected.
+  - _[Python in Markdown](http://example.com) by some
+    great folks_ - This *does* work as expected.
+  - [_Python in Markdown_](http://example.com) by some
+    great folks - This *does* work as expected.
+  - [_Python in Markdown_](http://example.com) _by some
+    great folks_ - This *does* work as expected.
+
+_[Python in Markdown](http://example.com) by some
+great folks_ - This *does* work as expected.
+
diff --git a/examples/misc/em_strong.txt b/examples/misc/em_strong.txt
new file mode 100644
index 0000000..1285665
--- /dev/null
+++ b/examples/misc/em_strong.txt
@@ -0,0 +1,21 @@
+One asterisk: *
+
+One underscore: _
+
+Two asterisks: **
+
+With spaces: * *
+
+Two underscores __
+
+with spaces: _ _
+
+three asterisks: ***
+
+with spaces: * * *
+
+three underscores: ___
+
+with spaces: _ _ _
+
+One char: _a_
diff --git a/examples/misc/em_strong_complex.txt b/examples/misc/em_strong_complex.txt
new file mode 100644
index 0000000..0425971
--- /dev/null
+++ b/examples/misc/em_strong_complex.txt
@@ -0,0 +1,27 @@
+___test test__ test test_
+
+___test test_ test test__
+
+___test___
+
+__test__
+
+___test_ test___
+
+___test_ test__
+
+_test_test test_test_
+
+***test test** test test*
+
+***test test* test test**
+
+**test*
+
+***test***
+
+**test***
+
+***test* test**
+
+*test*test test*test*
\ No newline at end of file
diff --git a/examples/misc/email.txt b/examples/misc/email.txt
new file mode 100644
index 0000000..c557c73
--- /dev/null
+++ b/examples/misc/email.txt
@@ -0,0 +1,5 @@
+
+asdfasdfadsfasd  or you can say 
+instead 
+
+
diff --git a/examples/misc/escaped_links.txt b/examples/misc/escaped_links.txt
new file mode 100644
index 0000000..c64ab26
--- /dev/null
+++ b/examples/misc/escaped_links.txt
@@ -0,0 +1,9 @@
+Backslashed in links:
+
+[q=go:GO\\:0000307](/query?q=go:GO\\:0000307)
+
+[q=go:GO\\:0000308][foo]
+
+[foo]: /query?q=go:GO\:0000308 "/query?q=go:GO\:0000308"
+
+a \non-escaped char.
\ No newline at end of file
diff --git a/examples/misc/funky-list.txt b/examples/misc/funky-list.txt
new file mode 100644
index 0000000..48ecd60
--- /dev/null
+++ b/examples/misc/funky-list.txt
@@ -0,0 +1,9 @@
+1. this starts a list *with* numbers
++  this will show as number "2"
+*  this will show as number "3."
+9. any number, +, -, or * will keep the list going.
+
+aaaaaaaaaaaaaaa
+
+- now a normal list
+- and more
diff --git a/examples/misc/h1.txt b/examples/misc/h1.txt
new file mode 100644
index 0000000..f67b921
--- /dev/null
+++ b/examples/misc/h1.txt
@@ -0,0 +1,13 @@
+Header
+------
+
+Header 2
+========
+
+### H3
+
+H1
+= 
+
+H2
+--
diff --git a/examples/misc/hash.txt b/examples/misc/hash.txt
new file mode 100644
index 0000000..634758d
--- /dev/null
+++ b/examples/misc/hash.txt
@@ -0,0 +1,13 @@
+a
+
+
                +#!/usr/bin/python
+hello
                
+
+a
+
+
                +!/usr/bin/python
+hello
                
+
+a
diff --git a/examples/misc/header-in-lists.txt b/examples/misc/header-in-lists.txt
new file mode 100644
index 0000000..b22083e
--- /dev/null
+++ b/examples/misc/header-in-lists.txt
@@ -0,0 +1,14 @@
+Tight List:
+
+* #Header1
+Line 1-2 - **not** a header *or* paragraph!
+* #Header2
+Line 2-2 - not a header or paragraph!
+
+Loose List:
+
+* #Header1
+Line 1-2 - *a* paragraph
+
+* #Header2
+Line 2-2 - a paragraph
diff --git a/examples/misc/headers.txt b/examples/misc/headers.txt
new file mode 100644
index 0000000..db114ed
--- /dev/null
+++ b/examples/misc/headers.txt
@@ -0,0 +1,15 @@
+### Hello world
+Line 2
+Line 3
+
+# [Markdown][5]  
+
+# [Markdown](http://some.link.com/)
+
+# [5]: http://foo.com/
+
+# Issue #1: Markdown
+
+Text
+# Header
+Some other text
diff --git a/examples/misc/hline.txt b/examples/misc/hline.txt
new file mode 100644
index 0000000..e39b7a2
--- /dev/null
+++ b/examples/misc/hline.txt
@@ -0,0 +1,5 @@
+
+#Header
+Next line
+
+
diff --git a/examples/misc/image-2.txt b/examples/misc/image-2.txt
new file mode 100644
index 0000000..6228383
--- /dev/null
+++ b/examples/misc/image-2.txt
@@ -0,0 +1,3 @@
+[*link!*](http://src.com/)
+
+*[link](http://www.freewisdom.org)*
diff --git a/examples/misc/image_in_links.txt b/examples/misc/image_in_links.txt
new file mode 100644
index 0000000..6d739e6
--- /dev/null
+++ b/examples/misc/image_in_links.txt
@@ -0,0 +1,3 @@
+
+
+[![altname](path/to/img_thumb.png)](path/to/image.png)
diff --git a/examples/misc/ins-at-start-of-paragraph.txt b/examples/misc/ins-at-start-of-paragraph.txt
new file mode 100644
index 0000000..2aee0bc
--- /dev/null
+++ b/examples/misc/ins-at-start-of-paragraph.txt
@@ -0,0 +1 @@
+Hello, fellow developer this ins should be wrapped in a p.
diff --git a/examples/misc/inside_html.txt b/examples/misc/inside_html.txt
new file mode 100644
index 0000000..4f068bf
--- /dev/null
+++ b/examples/misc/inside_html.txt
@@ -0,0 +1 @@
+ __ok__? 
diff --git a/examples/misc/japanese.txt b/examples/misc/japanese.txt
new file mode 100644
index 0000000..b2bd38c
--- /dev/null
+++ b/examples/misc/japanese.txt
@@ -0,0 +1,15 @@
+パイソン (Python)
+=======
+
+**Python**（パイソン）は、[Guido van Rossum](http://en.wikipedia.org/wiki/Guido_van_Rossum) によって作られたオープンソースのオブジェクト指向スクリプト言語。[Perl](http://ja.wikipedia.org/wiki/Perl)とともに欧米で広く普及している。イギリスのテレビ局 BBC が製作したコメディ番組『空飛ぶモンティ・パイソン』にちなんで名付けられた。 (Pythonには、爬虫類のニシキヘビの意味があり、Python言語のマスコットやアイコンとして使われることがある。)
+
+## 概要
+プログラミング言語 Python は初心者から専門家まで幅広いユーザ層を獲得している。利用目的は汎用で、方向性としてはJavaに近い。ただし、最初からネットワーク利用をメインとして考えられているJavaよりセキュリティについてはやや寛大である。多くのプラットフォームをサポートしており（⇒[動作するプラットフォーム](#somelink))、豊富なライブラリがあることから、産業界でも利用が増えつつある。また、Pythonは純粋なプログラミング言語のほかにも、多くの異なる言語で書かれたモジュールをまとめる糊言語のひとつとして位置づけることができる。実際Pythonは多くの商用アプリケーションでスクリプト言語として採用されている（⇒Pythonを使っている製品あるいはソフトウェアの一覧）。豊富なドキュメントをもち、Unicodeによる文字列操作をサポートしており、日本語処理も標準で可能である。
+
+Python は基本的にインタプリタ上で実行されることを念頭において設計されており、以下のような特徴をもっている:
+
+* 動的な型付け。
+* オブジェクトのメンバに対するアクセスが制限されていない。（属性や専用のメソッドフックを実装することによって制限は可能。）
+* モジュール、クラス、オブジェクト等の言語の要素が内部からアクセス可能であり、リフレクションを利用した記述が可能。
+
+また、Pythonではインデントによりブロックを指定する構文を採用している（⇒[オフサイドルール](#jklj)）。この構文はPythonに慣れたユーザからは称賛をもって受け入れられているが、他の言語のユーザからは批判も多い。このほかにも、大きすぎる実行ファイルや、Javaに比べて遅い処理速度などが欠点として指摘されている。しかし **プロトタイピング** の際にはこれらの点はさして問題とはならないことから、研究開発部門では頻繁に利用されている。
diff --git a/examples/misc/lazy-block-quote.txt b/examples/misc/lazy-block-quote.txt
new file mode 100644
index 0000000..e7c17ca
--- /dev/null
+++ b/examples/misc/lazy-block-quote.txt
@@ -0,0 +1,5 @@
+> Line one of lazy block quote.
+Line two of lazy block quote.
+
+> Line one of paragraph two.
+Line two of paragraph two.
diff --git a/examples/misc/link-with-parenthesis.txt b/examples/misc/link-with-parenthesis.txt
new file mode 100644
index 0000000..8affc98
--- /dev/null
+++ b/examples/misc/link-with-parenthesis.txt
@@ -0,0 +1 @@
+[ZIP archives](http://en.wikipedia.org/wiki/ZIP_(file_format) "ZIP (file format) - Wikipedia, the free encyclopedia")
diff --git a/examples/misc/lists.txt b/examples/misc/lists.txt
new file mode 100644
index 0000000..6db0dc3
--- /dev/null
+++ b/examples/misc/lists.txt
@@ -0,0 +1,31 @@
+
+* A multi-paragraph list, 
+unindented.
+
+
+
+Simple tight list
+
+* Uno
+* Due
+* Tri
+
+A singleton tight list:
+
+* Uno
+
+A lose list:
+
+* One
+
+* Two
+
+* Three
+
+A lose list with paragraphs
+
+* One one one one
+
+    one one one one
+
+* Two two two two
diff --git a/examples/misc/lists2.txt b/examples/misc/lists2.txt
new file mode 100644
index 0000000..cbff761
--- /dev/null
+++ b/examples/misc/lists2.txt
@@ -0,0 +1,3 @@
+* blah blah blah
+sdf asdf asdf asdf asdf
+asda asdf asdfasd
diff --git a/examples/misc/lists3.txt b/examples/misc/lists3.txt
new file mode 100644
index 0000000..6b45bd4
--- /dev/null
+++ b/examples/misc/lists3.txt
@@ -0,0 +1,3 @@
+* blah blah blah
+    sdf asdf asdf asdf asdf
+    asda asdf asdfasd
diff --git a/examples/misc/lists4.txt b/examples/misc/lists4.txt
new file mode 100644
index 0000000..a21493d
--- /dev/null
+++ b/examples/misc/lists4.txt
@@ -0,0 +1,5 @@
+
+* item1
+* item2
+    1. Number 1
+    2. Number 2
diff --git a/examples/misc/lists5.txt b/examples/misc/lists5.txt
new file mode 100644
index 0000000..566e0f1
--- /dev/null
+++ b/examples/misc/lists5.txt
@@ -0,0 +1,12 @@
+> This is a test of a block quote
+> With just two lines
+
+A paragraph
+
+> This is a more difficult case
+> With a list item inside the quote
+>
+> * Alpha
+> * Beta
+> Etc.
+
diff --git a/examples/misc/lists6.txt b/examples/misc/lists6.txt
new file mode 100644
index 0000000..f12788f
--- /dev/null
+++ b/examples/misc/lists6.txt
@@ -0,0 +1,14 @@
+Test five or more spaces as start of list:
+
+*     five spaces
+
+not first item:
+
+* one space
+*     five spaces
+
+loose list:
+
+* one space
+
+*     five spaces
diff --git a/examples/misc/lists7.txt b/examples/misc/lists7.txt
new file mode 100644
index 0000000..77181c8
--- /dev/null
+++ b/examples/misc/lists7.txt
@@ -0,0 +1,44 @@
+* item 1
+*   * item 2-1
+    * item 2-2
+    * item 2-3
+    * item 2-4
+* item 3
+*   * item 4-1
+
+    * item 4-2
+
+    * item 4-3
+
+    * item 4-4
+
+## same as above, different spacing
+* item 1
+* * item 2-1
+    * item 2-2
+* item 3
+* * item 4-1
+
+     * item 4-2
+
+## only 1 item in nested list ## 
+* item 1
+* * item 2-1
+* item 3
+* * item 4-1
+
+## Something ludicrous ## 
+* item 1
+* * item 2-1
+    * item 2-2
+    * * item 2-2-1
+        * item 2-2-2
+    * item 2-3
+* item 3
+* * item 4-1
+
+    * * item 4-1-1
+        * item 4-1-2
+
+    * item 4-2
+
diff --git a/examples/misc/lists8.txt b/examples/misc/lists8.txt
new file mode 100644
index 0000000..8ab6767
--- /dev/null
+++ b/examples/misc/lists8.txt
@@ -0,0 +1,16 @@
+# Lists with blockquotes
+1. > Four-score and seven years ago...
+
+2. > We have nothing to fear...
+
+3. > This is it...
+
+# Multi-line blockquotes
+* > Four-score and sever years ago
+  > our fathers brought forth
+
+* > We have nothing to fear
+  > but fear itself
+
+* > This is it
+  > as far as I'm concerned
diff --git a/examples/misc/missing-link-def.txt b/examples/misc/missing-link-def.txt
new file mode 100644
index 0000000..44bc656
--- /dev/null
+++ b/examples/misc/missing-link-def.txt
@@ -0,0 +1,4 @@
+This is a [missing link][empty] and a [valid][link] and [missing][again].
+
+[link]: http://example.com
+
diff --git a/examples/misc/multi-paragraph-block-quote.txt b/examples/misc/multi-paragraph-block-quote.txt
new file mode 100644
index 0000000..f8a986f
--- /dev/null
+++ b/examples/misc/multi-paragraph-block-quote.txt
@@ -0,0 +1,8 @@
+> This is line one of paragraph one
+> This is line two of paragraph one
+
+> This is line one of paragraph two
+
+
+
+> This is another blockquote.
diff --git a/examples/misc/multi-test.txt b/examples/misc/multi-test.txt
new file mode 100644
index 0000000..feaac31
--- /dev/null
+++ b/examples/misc/multi-test.txt
@@ -0,0 +1,26 @@
+Blah blah blah 
+
+* Basic list
+* Basic list 2
+
+addss
+
+ * Lazy list
+
+An [example][ref] (oops)
+
+  [ref]: http://example.com  "Title" 
+
+
+Now, let's use a footnote[^1].  Not bad, eh?
+Let's continue.
+
+  [^1]: Here is the text of the footnote
+    continued on several lines.
+    some more of the footnote, etc.
+
+    Actually, another paragraph too.
+
+And then there is a little bit of text.
+
+
diff --git a/examples/misc/nested-lists.txt b/examples/misc/nested-lists.txt
new file mode 100644
index 0000000..a2704b4
--- /dev/null
+++ b/examples/misc/nested-lists.txt
@@ -0,0 +1,33 @@
+* item 1
+
+    paragraph 2
+
+* item 2
+
+    * item 2-1
+    * item 2-2
+
+        * item 2-2-1
+
+    * item 2-3
+
+        * item 2-3-1
+
+* item 3
+
+plain text
+
+* item 1
+    * item 1-1
+    * item 1-2
+        * item 1-2-1
+* item 2
+* item 3
+* item 4
+    * item 4-1
+    * item 4-2
+    * item 4-3
+
+        Paragraph under item 4-3
+
+    Paragraph under item 4
diff --git a/examples/misc/nested-patterns.txt b/examples/misc/nested-patterns.txt
new file mode 100644
index 0000000..9032cf1
--- /dev/null
+++ b/examples/misc/nested-patterns.txt
@@ -0,0 +1,13 @@
+___[link](http://example.com)___
+***[link](http://example.com)***
+**[*link*](http://example.com)**
+__[_link_](http://example.com)__
+__[*link*](http://example.com)__
+**[_link_](http://example.com)**
+[***link***](http://example.com)
+
+***I am ___italic_ and__ bold* I am `just` bold**
+
+Example __*bold italic*__ on the same line __*bold italic*__.
+
+Example **_bold italic_** on the same line **_bold italic_**.
diff --git a/examples/misc/normalize.txt b/examples/misc/normalize.txt
new file mode 100644
index 0000000..fe0cf17
--- /dev/null
+++ b/examples/misc/normalize.txt
@@ -0,0 +1,2 @@
+
+[Link](http://www.stuff.com/q?x=1&y=2<>)
diff --git a/examples/misc/numeric-entity.txt b/examples/misc/numeric-entity.txt
new file mode 100644
index 0000000..fd2052b
--- /dev/null
+++ b/examples/misc/numeric-entity.txt
@@ -0,0 +1,4 @@
+
+
+
+This is an entity: ê 
diff --git a/examples/misc/para-with-hr.txt b/examples/misc/para-with-hr.txt
new file mode 100644
index 0000000..165bbe3
--- /dev/null
+++ b/examples/misc/para-with-hr.txt
@@ -0,0 +1,7 @@
+Here is a paragraph, followed by a horizontal rule.
+***
+Followed by another paragraph.
+
+Here is another paragraph, followed by:
+*** not an HR.
+Followed by more of the same paragraph.
diff --git a/examples/misc/russian.txt b/examples/misc/russian.txt
new file mode 100644
index 0000000..a742065
--- /dev/null
+++ b/examples/misc/russian.txt
@@ -0,0 +1,15 @@
+Недвард «Нед» Фландерс
+======================
+
+
+**Недвард «Нед» Фландерс** (Nedward «Ned» Flanders) — вымышленный персонаж мультсериала «[Симпсоны][]», озвученный Гарри Ширером. Он и его семья живут по соседству от семьи Симпсонов. Набожный христианин, Нед является одним из столпов морали Спрингфилда. В эпизоде «Alone Again, Natura-Diddily»  он овдовел, его жена Мод погибла в результате несчастного случая. 
+
+Нед был одним из первых персонажей в мультсериале, который не был членом семьи Симпсонов. Начиная с первых серий, он регулярно появляется в «Симпсонах». Считается, что Нед Фландерс был назван в честь улицы *Northeast Flanders St.* в [Портленде](http://www.portland.gov), Орегон, родном городе создателя мультсериала Мэтта Грейнинга]]. Надпись на указателе улицы *NE Flanders St.* хулиганы часто исправляли на _NED Flanders St._
+
+## Биография
+
+Нед Фландерс родился в Нью-Йорке, его родители были битниками. Его отец в точности похож на взрослого Неда, только он носил козлиную бородку. Их отказ от воспитания Неда и то, что они, в общем-то, были плохими родителями («мы ничего в этом не понимаем и не знаем как начать») привело к тому, что Нед превратился в ужасного сорванца. В конце концов они согласились на экспериментальную восьмимесячную шлепологическую терапию Миннесотского Университета (воспоминания Неда в эпизоде «Hurricane Neddy»), которая научила его подавлять чувство злости. Побочным эфектом терапии стало то, что Нед стал ненавидеть своих родителей (это одна из двух вещей которые ненавидит Фландерс, вторая — отделения почты, чьи длинные очереди, суета и угрюмый персонал раздражают его).
+
+У Неда есть странная привычка добавлять «дидли», «дадли» и другие бессмысленные слова в свои фразы при разговоре, например: «Hi-diddly-ho, neighbor-ino» («Приветик, соседушка»). Это результат сублимации его злости, вызванной сдерживанием гнева, который не имеет никакого другого выхода.
+
+
diff --git a/examples/misc/smart_em.txt b/examples/misc/smart_em.txt
new file mode 100644
index 0000000..3c56842
--- /dev/null
+++ b/examples/misc/smart_em.txt
@@ -0,0 +1,9 @@
+_emphasis_
+
+this_is_not_emphasis
+
+[_punctuation with emphasis_]
+
+[_punctuation_with_emphasis_]
+
+[punctuation_without_emphasis]
diff --git a/examples/misc/some-test.txt b/examples/misc/some-test.txt
new file mode 100644
index 0000000..0708817
--- /dev/null
+++ b/examples/misc/some-test.txt
@@ -0,0 +1,57 @@
+----------------------
+
+* as if
+	
+* as if2
+
+----------------------
+
+* as if
+    
+* as if2
+
+----------------------
+
+* as if
+    non_code
+* as if2
+
+
+
+
+Markdown
+
+*   Python
+    is ok
+    * Therefore i am
+
+* Perl sucks
+    big time
+    * But that's
+    ok
+
+* Python is
+ok
+    Or not?
+   
+Here is a normal paragraph
+
+1. Another list
+with a bunch of items
+2. Mostly fruits
+
+
+
+    3. Apple
+    4. Pare
+
+asdfasdfasd
+
+
+    # This is a code example
+    import stuff
+
+    Another code example
+    * Lists and similar stuff
+
+    > Should be ignored
diff --git a/examples/misc/span.txt b/examples/misc/span.txt
new file mode 100644
index 0000000..62bcf9b
--- /dev/null
+++ b/examples/misc/span.txt
@@ -0,0 +1,10 @@
+
+ Foo *bar* Baz 
+
+
                *foo*
                
+
+
                 Foo *bar* Baz 
                
+
+ Foo *bar* Baz 
+
+
diff --git a/examples/misc/strong-with-underscores.txt b/examples/misc/strong-with-underscores.txt
new file mode 100644
index 0000000..1a3544f
--- /dev/null
+++ b/examples/misc/strong-with-underscores.txt
@@ -0,0 +1 @@
+__this_is_strong__
diff --git a/examples/misc/stronintags.txt b/examples/misc/stronintags.txt
new file mode 100644
index 0000000..01c118f
--- /dev/null
+++ b/examples/misc/stronintags.txt
@@ -0,0 +1,8 @@
+this is a [**test**](http://example.com/)
+
+this is a second **[test](http://example.com)**
+
+reference **[test][]**
+reference [**test**][]
+
+
diff --git a/examples/misc/tabs-in-lists.txt b/examples/misc/tabs-in-lists.txt
new file mode 100644
index 0000000..05fde23
--- /dev/null
+++ b/examples/misc/tabs-in-lists.txt
@@ -0,0 +1,32 @@
+First a list with a tabbed line
+
+* A
+	
+* B
+
+Just a blank line:
+
+* A
+
+* B
+
+
+Now a list with 4 spaces and some text:
+
+* A
+    abcdef
+* B
+
+
+Now with a tab and an extra space:
+
+* A
+	 
+* B
+
+Now a list with 4 spaces:
+
+* A
+    
+* B
+
diff --git a/examples/misc/two-spaces.txt b/examples/misc/two-spaces.txt
new file mode 100644
index 0000000..61c19f7
--- /dev/null
+++ b/examples/misc/two-spaces.txt
@@ -0,0 +1,17 @@
+This line has two spaces at the end  
+but this one has none
+but this line has three   
+and this is the second from last line
+in this test message
+
+* This list item has two spaces.  
+* This has none.
+    This line has three.   
+    This line has none.
+    And this line two.  
+
+    This line has none.
+
+* This line has none.
+
+And this is the end.
diff --git a/examples/misc/uche.txt b/examples/misc/uche.txt
new file mode 100644
index 0000000..625d2ae
--- /dev/null
+++ b/examples/misc/uche.txt
@@ -0,0 +1,6 @@
+![asif](http://fourthought.com/images/ftlogo.png "Fourthought logo")
+
+[![Alt text](http://fourthought.com/images/ftlogo.png "Fourthought
+logo")](http://fourthought.com/)
+
+[![text](x)](http://link.com/)
diff --git a/examples/misc/underscores.txt b/examples/misc/underscores.txt
new file mode 100644
index 0000000..3c7f4bd
--- /dev/null
+++ b/examples/misc/underscores.txt
@@ -0,0 +1,11 @@
+THIS_SHOULD_STAY_AS_IS
+
+Here is some _emphasis_, ok?
+
+Ok, at least _this_ should work.
+
+THIS__SHOULD__STAY
+
+Here is some __strong__ stuff.
+
+THIS___SHOULD___STAY?
diff --git a/examples/misc/url_spaces.txt b/examples/misc/url_spaces.txt
new file mode 100644
index 0000000..3d2a82d
--- /dev/null
+++ b/examples/misc/url_spaces.txt
@@ -0,0 +1,4 @@
+[Dawn of War](http://wikipedia.org/wiki/Dawn of War)
+
+
+[Dawn of War](http://wikipedia.org/wiki/Dawn of War "Dawn of War")
diff --git a/src/generator.rs b/src/generator.rs
index ace16cb..3f30736 100644
--- a/src/generator.rs
+++ b/src/generator.rs
@@ -65,17 +65,23 @@ pub fn generate_html(
 pub fn markdown_to_html_with_extensions(
     markdown: &str,
 ) -> Result {
+    // Extract Markdown without front matter
     let content_without_front_matter =
         extract_front_matter(markdown).unwrap_or(markdown.to_string());
 
+    // Configure ComrakOptions for Markdown processing
     let mut comrak_options = ComrakOptions::default();
     comrak_options.extension.strikethrough = true;
     comrak_options.extension.table = true;
     comrak_options.extension.autolink = true;
     comrak_options.extension.tasklist = true;
-    comrak_options.render.escape = true;
     comrak_options.extension.superscript = true;
 
+    // Ensure raw HTML is allowed
+    comrak_options.render.unsafe_ = true;
+    comrak_options.render.escape = false;
+
+    // Use MarkdownOptions with the customized ComrakOptions
     let options =
         MarkdownOptions::default().with_comrak_options(comrak_options);
 
@@ -83,7 +89,7 @@ pub fn markdown_to_html_with_extensions(
     match process_markdown(&content_without_front_matter, &options) {
         Ok(html_output) => Ok(html_output),
         Err(err) => {
-            // Using the helper method
+            // Use the helper method to return an HtmlError
             Err(HtmlError::markdown_conversion(
                 err.to_string(),
                 None, // If err is not io::Error, use None
@@ -477,15 +483,24 @@ author: John Doe
         assert!(result.is_ok());
         let html = result.unwrap();
 
+        println!("Generated HTML:\n{}", html);
+
+        // Validate that raw HTML tags are not escaped
         assert!(
-            html.contains("<unexpected>"),
-            "HTML-like tags not escaped"
+            html.contains(""),
+            "Raw HTML tags like  should not be escaped"
         );
 
-        // Adjust expectation if the parser discards invalid links
+        // Validate that angle brackets in links are escaped
         assert!(
-            html.contains("<here>") || !html.contains(""),
-            "Angle brackets in link not handled correctly"
+            html.contains("<here>") || html.contains("<here)"),
+            "Angle brackets in links should be escaped for safety"
         );
+
+        // Validate the full header content
+        assert!(
+        html.contains("
                Invalid Markdown  [bad](url <here)
                "),
+        "Header not rendered correctly or content not properly handled"
+    );
     }
 }
diff --git a/src/performance.rs b/src/performance.rs
index bd0057c..b427563 100644
--- a/src/performance.rs
+++ b/src/performance.rs
@@ -555,10 +555,13 @@ mod tests {
                 assert!(message
                     .contains("Asynchronous HTML generation failed"));
                 assert!(source.is_some());
-                assert_eq!(
-            source.unwrap().to_string(),
-            "task 2 panicked with message \"Simulated task failure\"".to_string()
-        );
+
+                // Relax the assertion to match the general pattern of the panic message
+                let source_message = source.unwrap().to_string();
+                assert!(
+                    source_message.contains("Simulated task failure"),
+                    "Unexpected source message: {source_message}"
+                );
             }
         }
     }

From 4c31522f4ef0f5f48d23a2d55673e880f0e6cab2 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 18:13:00 +0000
Subject: [PATCH 28/34] docs(html-generator): :memo: constants should be
 documented more thoroughly

---
 src/lib.rs | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 808b9d7..6c30469 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -56,11 +56,11 @@ pub use utils::{extract_front_matter, format_header_with_id_class};
 
 /// Common constants used throughout the library
 pub mod constants {
-    /// Default maximum input size (5MB)
+    /// Maximum allowed input size (5MB) to prevent denial of service attacks
     pub const DEFAULT_MAX_INPUT_SIZE: usize = 5 * 1024 * 1024;
-    /// Minimum input size (1KB)
+    /// Minimum required input size (1KB) for meaningful processing
     pub const MIN_INPUT_SIZE: usize = 1024;
-    /// Default language code (en-GB)
+    /// Default language code for HTML generation (British English)
     pub const DEFAULT_LANGUAGE: &str = "en-GB";
     /// Default syntax highlighting theme (github)
     pub const DEFAULT_SYNTAX_THEME: &str = "github";

From 7bfe49b2232bb51048071b018b274b280dbfacdf Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 18:24:26 +0000
Subject: [PATCH 29/34] =?UTF-8?q?fix(html-generator):=20=F0=9F=90=9B=20ref?=
 =?UTF-8?q?actor=20the=20validate=5Flanguage=5Fcode?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/lib.rs | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 6c30469..d653433 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -448,7 +448,8 @@ pub fn markdown_file_to_html(
     Ok(())
 }
 
-/// Validates that a language code matches the required pattern
+/// Validates that a language code matches the BCP 47 format (e.g., "en-GB").
+/// Requires both language and region codes.
 ///
 /// # Arguments
 ///
@@ -456,13 +457,25 @@ pub fn markdown_file_to_html(
 ///
 /// # Returns
 ///
-/// Returns true if the language code is valid, false otherwise
-fn validate_language_code(lang: &str) -> bool {
+/// Returns true if the language code is valid (e.g., "en-GB"), false otherwise.
+///
+/// # Examples
+///
+/// ```
+/// use html_generator::validate_language_code;
+///
+/// assert!(validate_language_code("en-GB"));  // Valid
+/// assert!(!validate_language_code("en"));    // Invalid - missing region
+/// assert!(!validate_language_code("123"));   // Invalid - not a language code
+/// assert!(!validate_language_code("en_GB")); // Invalid - wrong separator
+/// ```
+pub fn validate_language_code(lang: &str) -> bool {
     use once_cell::sync::Lazy;
     use regex::Regex;
 
     static LANG_REGEX: Lazy = Lazy::new(|| {
-        Regex::new(constants::LANGUAGE_CODE_PATTERN).unwrap()
+        Regex::new(r"^[a-z]{2}(?:-[A-Z]{2})$")
+            .expect("Failed to compile language code regex")
     });
 
     LANG_REGEX.is_match(lang)

From 67fd3d5905bb73a731d3d5ab3361988ec3e59f26 Mon Sep 17 00:00:00 2001
From: Sebastien Rousseau 
Date: Sun, 1 Dec 2024 20:22:45 +0000
Subject: [PATCH 30/34] =?UTF-8?q?test(html-generator):=20=E2=9C=85=20add?=
 =?UTF-8?q?=20unit=20tests?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/lib.rs | 787 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 651 insertions(+), 136 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index d653433..9ba70b6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,41 +1,69 @@
-//! HTML Generator: A modern HTML generation and optimisation library
+//! HTML Generator: A modern HTML generation and optimization library
 //!
-//! `html-generator` is a comprehensive suite of tools for generating, optimising,
+//! `html-generator` is a comprehensive suite of tools for generating, optimizing,
 //! and managing HTML content with a focus on accessibility, SEO, and performance.
 //!
 //! # Features
 //!
-//! - **Markdown to HTML**: Convert Markdown content and files to HTML
-//! - **Accessibility**: Automated ARIA attributes and WCAG compliance checking
-//! - **SEO Optimisation**: Meta tag generation and structured data support
-//! - **Performance**: HTML minification and async generation capabilities
+//! - **Markdown to HTML**: Converts Markdown content and files to HTML with support for:
+//!   - CommonMark syntax
+//!   - GitHub Flavored Markdown
+//!   - Custom extensions and plugins
+//!
+//! - **Accessibility**:
+//!   - Automated ARIA attribute generation
+//!   - WCAG compliance checking
+//!   - Semantic HTML optimization
+//!
+//! - **SEO Optimization**:
+//!   - Meta tag generation
+//!   - Structured data (JSON-LD) support
+//!   - OpenGraph and Twitter card generation
+//!
+//! - **Performance**:
+//!   - HTML minification
+//!   - Async generation capabilities
+//!   - Memory-efficient processing
 //!
 //! # Examples
 //!
 //! ```rust
 //! use html_generator::{markdown_to_html, MarkdownConfig};
-//! # fn main() -> Result<(), html_generator::error::HtmlError> {
-//! let markdown = "# Hello World\n\nWelcome to HTML Generator.";
-//! let config = MarkdownConfig::default();
-//! let html = markdown_to_html(markdown, Some(config))?;
-//! println!("Generated HTML: {html}");
-//! # Ok(())
-//! # }
+//!
+//! fn main() -> Result<(), html_generator::error::HtmlError> {
+//!     let markdown = "# Hello World\n\nWelcome to HTML Generator.";
+//!     let config = MarkdownConfig::default();
+//!     let html = markdown_to_html(markdown, Some(config))?;
+//!     println!("Generated HTML: {html}");
+//!     Ok(())
+//! }
 //! ```
 //!
 //! # Security Features
 //!
-//! - Path validation to prevent directory traversal attacks
-//! - Input size limits to prevent denial of service
-//! - Unicode-aware text processing
-//! - Memory safety through Rust's guarantees
-//! - Comprehensive error handling to prevent undefined behaviour
+//! The library implements several security measures to protect against common vulnerabilities:
+//!
+//! - **Path Validation**: Prevents directory traversal attacks through strict path checking
+//! - **Input Limits**: Implements size restrictions to prevent denial of service attacks
+//! - **Unicode Safety**: Provides proper handling of Unicode text to prevent encoding attacks
+//! - **Memory Safety**: Leverages Rust's memory safety guarantees
+//! - **Error Handling**: Uses comprehensive error types to prevent undefined behavior
+//!
+//! # Architecture
+//!
+//! The library is organized into several key modules:
+//!
+//! - `accessibility`: ARIA attributes and WCAG compliance
+//! - `error`: Error types and handling
+//! - `generator`: Core HTML generation functionality
+//! - `performance`: Optimization and minification
+//! - `seo`: Search engine optimization features
+//! - `utils`: Utility functions and helpers
 
-use std::path::Component;
 use std::{
     fs::File,
     io::{self, Read, Write},
-    path::Path,
+    path::{Component, Path},
 };
 
 // Re-export public modules
@@ -46,7 +74,7 @@ pub mod performance;
 pub mod seo;
 pub mod utils;
 
-// Re-export primary types and functions
+// Re-export primary types and functions for convenience
 pub use crate::error::HtmlError;
 pub use accessibility::{add_aria_attributes, validate_wcag};
 pub use generator::generate_html;
@@ -54,20 +82,29 @@ pub use performance::{async_generate_html, minify_html};
 pub use seo::{generate_meta_tags, generate_structured_data};
 pub use utils::{extract_front_matter, format_header_with_id_class};
 
-/// Common constants used throughout the library
+/// Common constants used throughout the library.
+///
+/// This module contains configuration values and limits that help ensure
+/// secure and efficient operation of the library.
 pub mod constants {
     /// Maximum allowed input size (5MB) to prevent denial of service attacks
     pub const DEFAULT_MAX_INPUT_SIZE: usize = 5 * 1024 * 1024;
+
     /// Minimum required input size (1KB) for meaningful processing
     pub const MIN_INPUT_SIZE: usize = 1024;
+
     /// Default language code for HTML generation (British English)
     pub const DEFAULT_LANGUAGE: &str = "en-GB";
+
     /// Default syntax highlighting theme (github)
     pub const DEFAULT_SYNTAX_THEME: &str = "github";
+
     /// Maximum file path length
     pub const MAX_PATH_LENGTH: usize = 4096;
-    /// Valid language code pattern
+
+    /// Regular expression pattern for validating language codes
     pub const LANGUAGE_CODE_PATTERN: &str = r"^[a-z]{2}-[A-Z]{2}$";
+
     /// Verify invariants at compile time
     const _: () = assert!(MIN_INPUT_SIZE <= DEFAULT_MAX_INPUT_SIZE);
     const _: () = assert!(MAX_PATH_LENGTH > 0);
@@ -76,11 +113,15 @@ pub mod constants {
 /// Result type alias for library operations
 pub type Result = std::result::Result;
 
-/// Configuration options for Markdown to HTML conversion
+/// Configuration options for Markdown to HTML conversion.
+///
+/// This struct holds settings that control how Markdown content is processed
+/// and converted to HTML.
 #[derive(Debug, Clone, Eq, PartialEq)]
 pub struct MarkdownConfig {
     /// The encoding to use for input/output (defaults to "utf-8")
     pub encoding: String,
+
     /// HTML generation configuration
     pub html_config: HtmlConfig,
 }
@@ -94,7 +135,7 @@ impl Default for MarkdownConfig {
     }
 }
 
-/// Configuration error types
+/// Errors that can occur during configuration.
 #[derive(Debug, thiserror::Error)]
 pub enum ConfigError {
     /// Error for invalid input size configuration
@@ -102,30 +143,42 @@ pub enum ConfigError {
         "Invalid input size: {0} bytes is below minimum of {1} bytes"
     )]
     InvalidInputSize(usize, usize),
+
     /// Error for invalid language code
     #[error("Invalid language code: {0}")]
     InvalidLanguageCode(String),
+
     /// Error for invalid file path
     #[error("Invalid file path: {0}")]
     InvalidFilePath(String),
 }
 
-/// Output destination for HTML generation
-#[non_exhaustive] // Allow for future expansion
+/// Output destination for HTML generation.
+///
+/// Specifies where the generated HTML content should be written.
+#[non_exhaustive]
 pub enum OutputDestination {
     /// Write output to a file at the specified path
     File(String),
+
     /// Write output using a custom writer implementation
     ///
     /// This can be used for in-memory buffers, network streams,
     /// or other custom output destinations.
     Writer(Box),
+
     /// Write output to standard output (default)
     ///
     /// This is useful for command-line tools and scripts.
     Stdout,
 }
 
+impl Default for OutputDestination {
+    fn default() -> Self {
+        Self::Stdout
+    }
+}
+
 impl std::fmt::Debug for OutputDestination {
     fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
         match self {
@@ -138,29 +191,33 @@ impl std::fmt::Debug for OutputDestination {
     }
 }
 
-impl Default for OutputDestination {
-    fn default() -> Self {
-        Self::Stdout
-    }
-}
-
-/// Configuration options for HTML generation
+/// Configuration options for HTML generation.
+///
+/// Controls various aspects of the HTML generation process including
+/// syntax highlighting, accessibility features, and output formatting.
 #[derive(Debug, PartialEq, Eq, Clone)]
 pub struct HtmlConfig {
     /// Enable syntax highlighting for code blocks
     pub enable_syntax_highlighting: bool,
+
     /// Theme to use for syntax highlighting
     pub syntax_theme: Option,
+
     /// Minify the generated HTML output
     pub minify_output: bool,
+
     /// Automatically add ARIA attributes for accessibility
     pub add_aria_attributes: bool,
+
     /// Generate structured data (JSON-LD) based on content
     pub generate_structured_data: bool,
+
     /// Maximum size (in bytes) for input content
     pub max_input_size: usize,
+
     /// Language for generated content
     pub language: String,
+
     /// Enable table of contents generation
     pub generate_toc: bool,
 }
@@ -181,12 +238,32 @@ impl Default for HtmlConfig {
 }
 
 impl HtmlConfig {
-    /// Creates a new `HtmlConfig` with default options
+    /// Creates a new `HtmlConfig` using the builder pattern.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use html_generator::HtmlConfig;
+    ///
+    /// let config = HtmlConfig::builder()
+    ///     .with_syntax_highlighting(true, Some("monokai".to_string()))
+    ///     .with_language("en-GB")
+    ///     .build()
+    ///     .unwrap();
+    /// ```
     pub fn builder() -> HtmlConfigBuilder {
         HtmlConfigBuilder::default()
     }
 
-    /// Validates the configuration
+    /// Validates the configuration settings.
+    ///
+    /// Checks that all configuration values are within acceptable ranges
+    /// and conform to required formats.
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` if the configuration is valid, or an appropriate
+    /// error if validation fails.
     pub fn validate(&self) -> Result<()> {
         if self.max_input_size < constants::MIN_INPUT_SIZE {
             return Err(HtmlError::InvalidInput(format!(
@@ -203,7 +280,16 @@ impl HtmlConfig {
         Ok(())
     }
 
-    /// Validates file path safety
+    /// Validates file path safety to prevent directory traversal attacks.
+    ///
+    /// # Arguments
+    ///
+    /// * `path` - The file path to validate
+    ///
+    /// # Returns
+    ///
+    /// Returns `Ok(())` if the path is safe, or an appropriate error
+    /// if validation fails.
     pub(crate) fn validate_file_path(
         path: impl AsRef,
     ) -> Result<()> {
@@ -230,7 +316,6 @@ impl HtmlConfig {
             ));
         }
 
-        // Only check absolute paths in non-test mode
         #[cfg(not(test))]
         if path.is_absolute() {
             return Err(HtmlError::InvalidInput(
@@ -251,19 +336,27 @@ impl HtmlConfig {
     }
 }
 
-/// Builder for `HtmlConfig` to customize HTML generation options
+/// Builder for constructing `HtmlConfig` instances.
+///
+/// Provides a fluent interface for creating and customizing HTML
+/// configuration options.
 #[derive(Debug, Default)]
 pub struct HtmlConfigBuilder {
     config: HtmlConfig,
 }
 
 impl HtmlConfigBuilder {
-    /// Creates a new `HtmlConfigBuilder` with default options
+    /// Creates a new `HtmlConfigBuilder` with default options.
     pub fn new() -> Self {
         Self::default()
     }
 
-    /// Enable or disable syntax highlighting for code blocks
+    /// Enables or disables syntax highlighting for code blocks.
+    ///
+    /// # Arguments
+    ///
+    /// * `enable` - Whether to enable syntax highlighting
+    /// * `theme` - Optional theme name for syntax highlighting
     #[must_use]
     pub fn with_syntax_highlighting(
         mut self,
@@ -279,27 +372,32 @@ impl HtmlConfigBuilder {
         self
     }
 
-    /// Set the language for generated content
+    /// Sets the language for generated content.
+    ///
+    /// # Arguments
+    ///
+    /// * `language` - The language code (e.g., "en-GB")
     #[must_use]
     pub fn with_language(
         mut self,
         language: impl Into,
     ) -> Self {
-        // Store the language value regardless of validation
-        // Validation will happen during build()
         self.config.language = language.into();
         self
     }
 
-    /// Build the configuration, validating all settings
+    /// Builds the configuration, validating all settings.
+    ///
+    /// # Returns
+    ///
+    /// Returns the validated configuration or an error if validation fails.
     pub fn build(self) -> Result {
-        // Validate the configuration before returning
         self.config.validate()?;
         Ok(self.config)
     }
 }
 
-/// Convert Markdown content to HTML
+/// Converts Markdown content to HTML.
 ///
 /// This function processes Unicode Markdown content and returns HTML output.
 /// The input must be valid Unicode - if your input is encoded (e.g., UTF-8),
@@ -325,12 +423,11 @@ impl HtmlConfigBuilder {
 ///
 /// ```rust
 /// use html_generator::{markdown_to_html, MarkdownConfig};
-/// # fn main() -> Result<(), html_generator::error::HtmlError> {
+///
 /// let markdown = "# Hello\n\nWorld";
 /// let html = markdown_to_html(markdown, None)?;
 /// assert!(html.contains("
                Hello
                "));
-/// # Ok(())
-/// # }
+/// # Ok::<(), html_generator::error::HtmlError>(())
 /// ```
 pub fn markdown_to_html(
     content: &str,
@@ -351,7 +448,7 @@ pub fn markdown_to_html(
     generate_html(content, &config.html_config)
 }
 
-/// Convert a Markdown file to HTML
+/// Converts a Markdown file to HTML.
 ///
 /// This function reads from a file or stdin and writes the generated HTML to
 /// a specified destination. It handles encoding/decoding of content.
@@ -364,33 +461,16 @@ pub fn markdown_to_html(
 ///
 /// # Returns
 ///
-/// Returns `Ok(())` on success or an error if the operation fails
+/// Returns `Ok
 ///
 /// # Errors
 ///
 /// Returns an error if:
-/// * The input file cannot be read
-/// * The output cannot be written
-/// * The content cannot be decoded/encoded with the specified encoding
-/// * HTML generation fails
+/// * Input file is not found or cannot be read
+/// * Output file cannot be written
+/// * Configuration is invalid
 /// * Input size exceeds configured maximum
 ///
-/// # Examples
-///
-/// ```no_run
-/// use html_generator::{markdown_file_to_html, MarkdownConfig, OutputDestination};
-/// # fn main() -> Result<(), html_generator::error::HtmlError> {
-/// let config = MarkdownConfig::default();
-/// let output = OutputDestination::File("output.html".to_string());
-///
-/// markdown_file_to_html(
-///     Some("input.md"),
-///     Some(output),
-///     Some(config)
-/// )?;
-/// # Ok(())
-/// # }
-/// ```
 pub fn markdown_file_to_html(
     input: Option>,
     output: Option,
@@ -449,7 +529,9 @@ pub fn markdown_file_to_html(
 }
 
 /// Validates that a language code matches the BCP 47 format (e.g., "en-GB").
-/// Requires both language and region codes.
+///
+/// This function checks if a given language code follows the BCP 47 format,
+/// which requires both language and region codes.
 ///
 /// # Arguments
 ///
@@ -461,7 +543,7 @@ pub fn markdown_file_to_html(
 ///
 /// # Examples
 ///
-/// ```
+/// ```rust
 /// use html_generator::validate_language_code;
 ///
 /// assert!(validate_language_code("en-GB"));  // Valid
@@ -484,17 +566,19 @@ pub fn validate_language_code(lang: &str) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use regex::Regex;
     use std::io::Cursor;
     use tempfile::{tempdir, TempDir};
 
-    /// Helper function to create a temporary test directory.
+    /// Creates a temporary test directory for file operations.
     ///
-    /// Returns a TempDir that will automatically clean up when dropped.
+    /// The directory and its contents are automatically cleaned up when
+    /// the returned TempDir is dropped.
     fn setup_test_dir() -> TempDir {
         tempdir().expect("Failed to create temporary directory")
     }
 
-    /// Helper function to create a test file with the given content.
+    /// Creates a test file with the given content.
     ///
     /// # Arguments
     ///
@@ -514,7 +598,6 @@ mod tests {
         path
     }
 
-    /// Tests for configuration-related functionality
     mod config_tests {
         use super::*;
 
@@ -565,21 +648,86 @@ mod tests {
                 .with_language("invalid")
                 .build();
 
-            assert!(result.is_err());
-            match result {
-                Err(HtmlError::InvalidInput(msg)) => {
-                    assert!(msg.contains("Invalid language code"),
-                "Expected error message about invalid language code, got: {}", msg);
-                }
-                err => panic!(
-                    "Expected InvalidInput error, got: {:?}",
-                    err
-                ),
-            }
+            assert!(matches!(
+                result,
+                Err(HtmlError::InvalidInput(msg)) if msg.contains("Invalid language code")
+            ));
+        }
+
+        #[test]
+        fn test_html_config_with_no_syntax_theme() {
+            let config = HtmlConfig {
+                enable_syntax_highlighting: true,
+                syntax_theme: None,
+                ..Default::default()
+            };
+
+            assert!(config.validate().is_ok());
+        }
+
+        #[test]
+        fn test_file_conversion_with_large_output() -> Result<()> {
+            let temp_dir = setup_test_dir();
+            let input_path = create_test_file(
+                &temp_dir,
+                "# Large\n\nContent".repeat(10_000).as_str(),
+            );
+            let output_path = temp_dir.path().join("large_output.html");
+
+            let result = markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::File(
+                    output_path.to_string_lossy().into(),
+                )),
+                None,
+            );
+
+            assert!(result.is_ok());
+            let content = std::fs::read_to_string(output_path)?;
+            assert!(content.contains("
                Large
                "));
+
+            Ok(())
+        }
+
+        #[test]
+        fn test_markdown_with_broken_syntax() {
+            let markdown = "# Unmatched Header\n**Bold start";
+            let result = markdown_to_html(markdown, None);
+            assert!(result.is_ok());
+            let html = result.unwrap();
+            assert!(html.contains("
                Unmatched Header
                "));
+            assert!(html.contains("**Bold start
                ")); // Ensure content is preserved
+        }
+
+        #[test]
+        fn test_language_code_with_custom_regex() {
+            let custom_lang_regex =
+                Regex::new(r"^[a-z]{2}-[A-Z]{2}$").unwrap();
+            assert!(custom_lang_regex.is_match("en-GB"));
+            assert!(!custom_lang_regex.is_match("EN-gb")); // Case-sensitive check
+        }
+
+        #[test]
+        fn test_markdown_to_html_error_handling() {
+            let result = markdown_to_html("", None);
+            assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
+
+            let oversized_input =
+                "a".repeat(constants::DEFAULT_MAX_INPUT_SIZE + 1);
+            let result = markdown_to_html(&oversized_input, None);
+            assert!(matches!(result, Err(HtmlError::InputTooLarge(_))));
+        }
+
+        #[test]
+        fn test_performance_with_nested_lists() {
+            let nested_list = "- Item\n".repeat(1000);
+            let result = markdown_to_html(&nested_list, None);
+            assert!(result.is_ok());
+            let html = result.unwrap();
+            assert!(html.matches("
              • ").count() == 1000);
         }
     }
 
-    /// Tests for file path validation
     mod file_validation_tests {
         use super::*;
         use std::path::PathBuf;
@@ -620,16 +768,8 @@ mod tests {
                 );
             }
         }
-
-        #[test]
-        #[cfg(not(test))]
-        fn test_absolute_paths() {
-            let path = PathBuf::from("/absolute/path/test.md");
-            assert!(HtmlConfig::validate_file_path(&path).is_err());
-        }
     }
 
-    /// Tests for Markdown conversion functionality
     mod markdown_conversion_tests {
         use super::*;
 
@@ -657,27 +797,28 @@ mod tests {
 
             let result = markdown_to_html(markdown, Some(config));
             assert!(result.is_ok());
-
-            let html = result.unwrap();
-            assert!(html.contains("language-rust"));
+            assert!(result.unwrap().contains("language-rust"));
         }
 
         #[test]
         fn test_empty_content() {
-            let result = markdown_to_html("", None);
-            assert!(matches!(result, Err(HtmlError::InvalidInput(_))));
+            assert!(matches!(
+                markdown_to_html("", None),
+                Err(HtmlError::InvalidInput(_))
+            ));
         }
 
         #[test]
         fn test_content_too_large() {
             let large_content =
                 "a".repeat(constants::DEFAULT_MAX_INPUT_SIZE + 1);
-            let result = markdown_to_html(&large_content, None);
-            assert!(matches!(result, Err(HtmlError::InputTooLarge(_))));
+            assert!(matches!(
+                markdown_to_html(&large_content, None),
+                Err(HtmlError::InputTooLarge(_))
+            ));
         }
     }
 
-    /// Tests for file-based operations
     mod file_operation_tests {
         use super::*;
 
@@ -688,16 +829,15 @@ mod tests {
                 create_test_file(&temp_dir, "# Test\n\nHello world");
             let output_path = temp_dir.path().join("test.html");
 
-            let result = markdown_file_to_html(
+            markdown_file_to_html(
                 Some(&input_path),
                 Some(OutputDestination::File(
                     output_path.to_string_lossy().into(),
                 )),
                 None::,
-            );
+            )?;
 
-            assert!(result.is_ok());
-            let content = std::fs::read_to_string(&output_path)?;
+            let content = std::fs::read_to_string(output_path)?;
             assert!(content.contains("
                Test
                "));
 
             Ok(())
@@ -705,7 +845,6 @@ mod tests {
 
         #[test]
         fn test_writer_output() {
-            // Create a test file instead of using stdin
             let temp_dir = setup_test_dir();
             let input_path =
                 create_test_file(&temp_dir, "# Test\nHello");
@@ -725,16 +864,15 @@ mod tests {
             let buffer = Box::new(Cursor::new(Vec::new()));
 
             let result = markdown_file_to_html(
-                Some(Path::new("nonexistent.md")), // Use nonexistent file instead of None
+                Some(Path::new("nonexistent.md")),
                 Some(OutputDestination::Writer(buffer)),
                 None,
             );
 
-            assert!(result.is_err()); // Should fail with file not found error
+            assert!(result.is_err());
         }
     }
 
-    /// Tests for language code validation
     mod language_validation_tests {
         use super::*;
 
@@ -774,7 +912,6 @@ mod tests {
         }
     }
 
-    /// Integration tests for end-to-end functionality
     mod integration_tests {
         use super::*;
 
@@ -819,27 +956,6 @@ This is a test document with:
             Ok(())
         }
 
-        #[test]
-        fn test_error_handling() {
-            // Test non-existent file
-            let result = markdown_file_to_html(
-                Some(Path::new("nonexistent.md")),
-                None,
-                None,
-            );
-            assert!(result.is_err());
-
-            // Test invalid output path
-            let result = markdown_file_to_html(
-                Some(Path::new("test.md")),
-                Some(OutputDestination::File(
-                    "/invalid/path/test.html".to_string(),
-                )),
-                None,
-            );
-            assert!(result.is_err());
-        }
-
         #[test]
         fn test_output_destination_debug() {
             assert_eq!(
@@ -853,6 +969,7 @@ This is a test document with:
                 format!("{:?}", OutputDestination::Stdout),
                 "Stdout"
             );
+
             let writer = Box::new(Cursor::new(Vec::new()));
             assert_eq!(
                 format!("{:?}", OutputDestination::Writer(writer)),
@@ -860,4 +977,402 @@ This is a test document with:
             );
         }
     }
+
+    mod markdown_config_tests {
+        use super::*;
+
+        #[test]
+        fn test_markdown_config_custom_encoding() {
+            let config = MarkdownConfig {
+                encoding: "latin1".to_string(),
+                html_config: HtmlConfig::default(),
+            };
+            assert_eq!(config.encoding, "latin1");
+        }
+
+        #[test]
+        fn test_markdown_config_default() {
+            let config = MarkdownConfig::default();
+            assert_eq!(config.encoding, "utf-8");
+            assert_eq!(config.html_config, HtmlConfig::default());
+        }
+
+        #[test]
+        fn test_markdown_config_clone() {
+            let config = MarkdownConfig::default();
+            let cloned = config.clone();
+            assert_eq!(config, cloned);
+        }
+    }
+
+    mod config_error_tests {
+        use super::*;
+
+        #[test]
+        fn test_config_error_display() {
+            let error = ConfigError::InvalidInputSize(100, 1024);
+            assert!(error.to_string().contains("Invalid input size"));
+
+            let error =
+                ConfigError::InvalidLanguageCode("xx".to_string());
+            assert!(error
+                .to_string()
+                .contains("Invalid language code"));
+
+            let error =
+                ConfigError::InvalidFilePath("../bad/path".to_string());
+            assert!(error.to_string().contains("Invalid file path"));
+        }
+    }
+
+    mod output_destination_tests {
+        use super::*;
+
+        #[test]
+        fn test_output_destination_default() {
+            assert!(matches!(
+                OutputDestination::default(),
+                OutputDestination::Stdout
+            ));
+        }
+
+        #[test]
+        fn test_output_destination_file() {
+            let dest = OutputDestination::File("test.html".to_string());
+            assert!(matches!(dest, OutputDestination::File(_)));
+        }
+
+        #[test]
+        fn test_output_destination_writer() {
+            let writer = Box::new(Cursor::new(Vec::new()));
+            let dest = OutputDestination::Writer(writer);
+            assert!(matches!(dest, OutputDestination::Writer(_)));
+        }
+    }
+
+    mod html_config_tests {
+        use super::*;
+
+        #[test]
+        fn test_html_config_builder_all_options() {
+            let config = HtmlConfig::builder()
+                .with_syntax_highlighting(
+                    true,
+                    Some("dracula".to_string()),
+                )
+                .with_language("en-US")
+                .build()
+                .unwrap();
+
+            assert!(config.enable_syntax_highlighting);
+            assert_eq!(
+                config.syntax_theme,
+                Some("dracula".to_string())
+            );
+            assert_eq!(config.language, "en-US");
+        }
+
+        #[test]
+        fn test_html_config_validation_edge_cases() {
+            let config = HtmlConfig {
+                max_input_size: constants::MIN_INPUT_SIZE,
+                ..Default::default()
+            };
+            assert!(config.validate().is_ok());
+
+            let config = HtmlConfig {
+                max_input_size: constants::MIN_INPUT_SIZE - 1,
+                ..Default::default()
+            };
+            assert!(config.validate().is_err());
+        }
+    }
+
+    mod markdown_processing_tests {
+        use super::*;
+
+        #[test]
+        fn test_markdown_to_html_with_front_matter() -> Result<()> {
+            let markdown = r#"---
+title: Test
+author: Test Author
+---
+# Heading
+Content"#;
+            let html = markdown_to_html(markdown, None)?;
+            assert!(html.contains("
                Heading
                "));
+            assert!(html.contains("
                Content
                "));
+            Ok(())
+        }
+
+        #[test]
+        fn test_markdown_to_html_with_code_blocks() -> Result<()> {
+            let markdown = r#"```rust
+fn main() {
+    println!("Hello");
+}
+```"#;
+            let config = MarkdownConfig {
+                html_config: HtmlConfig {
+                    enable_syntax_highlighting: true,
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
+            let html = markdown_to_html(markdown, Some(config))?;
+            assert!(html.contains("language-rust"));
+            Ok(())
+        }
+
+        #[test]
+        fn test_markdown_to_html_with_tables() -> Result<()> {
+            let markdown = r#"
+| Header 1 | Header 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+"#;
+            let html = markdown_to_html(markdown, None)?;
+            // First verify the HTML output to see what we're getting
+            println!("Generated HTML for table: {}", html);
+            // Check for common table elements - div wrapper is often used for table responsiveness
+            assert!(html.contains("Header 1"));
+            assert!(html.contains("Cell 1"));
+            assert!(html.contains("Cell 2"));
+            Ok(())
+        }
+
+        #[test]
+        fn test_invalid_encoding_handling() {
+            let config = MarkdownConfig {
+                encoding: "unsupported-encoding".to_string(),
+                html_config: HtmlConfig::default(),
+            };
+            // Simulate usage where encoding matters
+            let result = markdown_to_html("# Test", Some(config));
+            assert!(result.is_ok()); // Assuming encoding isn't directly validated during processing
+        }
+
+        #[test]
+        fn test_config_error_types() {
+            let error = ConfigError::InvalidInputSize(512, 1024);
+            assert_eq!(format!("{}", error), "Invalid input size: 512 bytes is below minimum of 1024 bytes");
+        }
+    }
+
+    mod file_processing_tests {
+        use crate::{
+            markdown_file_to_html, HtmlError, OutputDestination,
+        };
+        use std::path::Path;
+        use tempfile::NamedTempFile;
+
+        #[test]
+        fn test_file_to_html_invalid_input() {
+            let result = markdown_file_to_html(
+                Some(Path::new("nonexistent.md")),
+                None,
+                None,
+            );
+            assert!(matches!(result, Err(HtmlError::Io(_))));
+        }
+
+        #[test]
+        fn test_file_to_html_with_invalid_output_path(
+        ) -> Result<(), HtmlError> {
+            let input = NamedTempFile::new()?;
+            std::fs::write(&input, "# Test")?;
+
+            let result = markdown_file_to_html(
+                Some(input.path()),
+                Some(OutputDestination::File(
+                    "/invalid/path/test.html".to_string(),
+                )),
+                None,
+            );
+            assert!(result.is_err());
+            Ok(())
+        }
+    }
+
+    mod language_validation_extended_tests {
+        use super::*;
+
+        #[test]
+        fn test_language_code_edge_cases() {
+            // Test empty string
+            assert!(!validate_language_code(""));
+
+            // Test single character
+            assert!(!validate_language_code("a"));
+
+            // Test incorrect casing
+            assert!(!validate_language_code("EN-GB"));
+            assert!(!validate_language_code("en-gb"));
+
+            // Test invalid separators
+            assert!(!validate_language_code("en_GB"));
+            assert!(!validate_language_code("en GB"));
+
+            // Test too many segments
+            assert!(!validate_language_code("en-GB-extra"));
+        }
+
+        #[test]
+        fn test_language_code_special_cases() {
+            // Test with numbers
+            assert!(!validate_language_code("e1-GB"));
+            assert!(!validate_language_code("en-G1"));
+
+            // Test with special characters
+            assert!(!validate_language_code("en-GB!"));
+            assert!(!validate_language_code("en@GB"));
+
+            // Test with Unicode characters
+            assert!(!validate_language_code("あa-GB"));
+            assert!(!validate_language_code("en-あa"));
+        }
+    }
+
+    mod integration_extended_tests {
+        use super::*;
+
+        #[test]
+        fn test_full_conversion_pipeline() -> Result<()> {
+            // Create temporary files
+            let temp_dir = tempdir()?;
+            let input_path = temp_dir.path().join("test.md");
+            let output_path = temp_dir.path().join("test.html");
+
+            // Test content with various Markdown features
+            let content = r#"---
+title: Test Document
+author: Test Author
+---
+
+# Main Heading
+
+## Subheading
+
+This is a paragraph with *italic* and **bold** text.
+
+- List item 1
+- List item 2
+  - Nested item
+  - Another nested item
+
+```rust
+fn main() {
+    println!("Hello, world!");
+}
+```
+
+| Column 1 | Column 2 |
+|----------|----------|
+| Cell 1   | Cell 2   |
+
+> This is a blockquote
+
+[Link text](https://example.com)"#;
+
+            std::fs::write(&input_path, content)?;
+
+            // Configure with all features enabled
+            let config = MarkdownConfig {
+                html_config: HtmlConfig {
+                    enable_syntax_highlighting: true,
+                    generate_toc: true,
+                    add_aria_attributes: true,
+                    generate_structured_data: true,
+                    minify_output: true,
+                    ..Default::default()
+                },
+                ..Default::default()
+            };
+
+            markdown_file_to_html(
+                Some(&input_path),
+                Some(OutputDestination::File(
+                    output_path.to_string_lossy().into(),
+                )),
+                Some(config),
+            )?;
+
+            let html = std::fs::read_to_string(&output_path)?;
+
+            // Verify all expected elements are present
+            println!("Generated HTML: {}", html);
+            assert!(html.contains("
                "));
+            assert!(html.contains("
                "));
+            assert!(html.contains(""));
+            assert!(html.contains(""));
+            assert!(html.contains("