MDX Generator (mdx-gen)

A robust Rust library for processing Markdown into responsive HTML, offering custom blocks, syntax highlighting, and enhanced table formatting for richer content.

• Website • Documentation • Report Bug • Request Feature • Contributing Guidelines

Overview

mdx-gen is a flexible Rust library that converts Markdown into HTML, providing enhanced features like custom block extensions, syntax highlighting, and table formatting.

mdx-gen uses the high-performance comrak library for Markdown parsing and offers flexible options for modifying and extending Markdown behavior.

Key Features

• Markdown to HTML Conversion: Converts Markdown to responsive HTML using the comrak parser, ensuring fast and accurate rendering of Markdown content.
• Custom Block Extensions: Allows the use of custom blocks such as notes, warnings, and tips, transforming them into structured HTML elements for improved content formatting.
• Syntax Highlighting: Automatically applies syntax highlighting to code blocks for a wide range of programming languages, making code snippets more readable and professional.
• Enhanced Table Formatting: Converts Markdown tables into responsive HTML tables with proper alignment and additional styling for better usability across devices.
• Flexible Configuration: Provides a customizable MarkdownOptions structure that allows developers to enable or disable specific features (e.g., custom blocks, enhanced tables, or syntax highlighting).
• Error Handling: Comprehensive error handling system with detailed error reporting to ensure smooth Markdown processing, even in complex cases.

Supported Extensions

mdx-gen offers the following extensions, which can be enabled or disabled individually via MarkdownOptions:

• Custom blocks (notes, warnings, tips)
• Enhanced table formatting with responsive design
• Syntax highlighting for code blocks
• Strikethrough and autolink support
• Advanced error reporting for improved debugging

Installation

Add this to your Cargo.toml:

[dependencies]
mdx-gen = "0.0.1"

Usage

Here are some examples of how to use the library:

Basic Usage

use mdx_gen::{process_markdown, MarkdownOptions};

let markdown_content = "# Hello, world!\n\nThis is a paragraph.";
let options = MarkdownOptions::new()
    .with_enhanced_tables(false);
let html = process_markdown(markdown_content, &options).unwrap();
println!("HTML output: {}", html);

Custom Blocks and Syntax Highlighting

use mdx_gen::{process_markdown, MarkdownOptions};

let markdown_content = r#"
# Example

<div class="note">This is a note.</div>

``rust
fn main() {
    println!("Hello, world!");
}
"#;

let options = MarkdownOptions::new()
    .with_custom_blocks(true)
    .with_syntax_highlighting(true)
    .with_enhanced_tables(true)
    .with_comrak_options({
        let mut opts = comrak::ComrakOptions::default();
        opts.extension.table = true;
        opts
    });

let html = process_markdown(markdown_content, &options).unwrap();
println!("HTML output: {}", html);

Modules

• lib.rs: The main library module that ties everything together.
• markdown.rs: Core functionality for Markdown processing and conversion.
• extensions.rs: Handles custom block extensions, syntax highlighting, and table processing.
• error.rs: Defines error types and implements error handling for the library.

Documentation

For full API documentation, please visit docs.rs/mdx-gen.

Examples

To run the examples, clone the repository and use the following command:

cargo run --example example_name

Replace example_name with the name of the example you want to run.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

License

The project is dual-licensed under the terms of both the MIT license and the Apache License (Version 2.0).

• Apache License, Version 2.0
• MIT license

at your option.

Acknowledgements

Special thanks to all contributors who have helped build the mdx-gen library.