Rust Markdown解析库md2使用指南

介绍

md2是一个高效轻量级的Rust Markdown解析库，专注于将Markdown文本转换为HTML。它具有以下特点：

• 轻量级：代码库小巧，依赖少
• 高效：解析速度快，内存占用低
• 简单易用：提供简洁的API接口
• 支持标准Markdown语法

安装方法

在Cargo.toml中添加依赖：

[dependencies]
md2 = "0.1.0"  # 请使用最新版本号

基本使用方法

简单转换

use md2::html;

fn main() {
    let markdown = "# Hello, md2!\n\nThis is a **Markdown** parser.";
    let html = html::to_html(markdown);
    println!("{}", html);
}

输出结果：

<h1>Hello, md2!</h1>
<p>This is a <strong>Markdown</strong> parser.</p>

处理文件

use md2::html;
use std::fs;

fn main() {
    let markdown_content = fs::read_to_string("example.md").unwrap();
    let html_content = html::to_html(&markdown_content);
    fs::write("output.html", html_content).unwrap();
}

高级功能

自定义渲染选项

use md2::{html, HtmlOptions};

fn main() {
    let options = HtmlOptions {
        hard_breaks: true,  // 将换行符转换为<br>
        safe_mode: true,    // 过滤危险HTML
        ..Default::default()
    };
    
    let markdown = "Line 1\nLine 2";
    let html = html::to_html_with_options(markdown, &options);
    println!("{}", html);
}

提取纯文本

use md2::text;

fn main() {
    let markdown = "# Title\n\nSome *text* with **formatting**";
    let plain_text = text::to_text(markdown);
    println!("{}", plain_text);
    // 输出: Title Some text with formatting
}

性能优化

对于大量Markdown处理，可以使用缓冲方式：

use md2::html;
use std::io::{BufReader, BufWriter};

fn process_large_file(input_path: &str, output_path: &str) {
    let input = std::fs::File::open(input_path).unwrap();
    let reader = BufReader::new(input);
    
    let output = std::fs::File::create(output_path).unwrap();
    let mut writer = BufWriter::new(output);
    
    html::to_html_buffered(reader, &mut writer).unwrap();
}

支持的Markdown语法

md2支持以下常见Markdown语法：

• 标题 (#, ##, …)
• 列表 (有序和无序)
• 链接和图片
• 强调 (italic, bold)
• 代码块和内联代码
• 引用块
• 水平线

注意事项

1. md2目前不支持表格和HTML内嵌
2. 对于超大文件(>10MB)，建议使用缓冲处理方式
3. 安全模式下会过滤掉<script>等危险标签

示例项目结构

一个典型的Markdown处理项目可以这样组织：

my_markdown_app/
├── Cargo.toml
├── src/
│   ├── main.rs
├── input/
│   ├── example.md
└── output/
    └── (生成的HTML文件)

完整示例demo

下面是一个完整的Markdown处理项目示例，包含文件处理和自定义选项：

// src/main.rs
use md2::{html, text, HtmlOptions};
use std::fs;
use std::path::Path;
use std::io::{BufReader, BufWriter};

fn main() {
    // 创建输入输出目录
    create_dir_if_not_exists("input");
    create_dir_if_not_exists("output");
    
    // 示例1: 简单Markdown转换
    simple_conversion();
    
    // 示例2: 文件处理
    file_processing();
    
    // 示例3: 自定义选项处理
    custom_options_processing();
    
    // 示例4: 大文件缓冲处理
    large_file_processing("input/large.md", "output/large.html");
}

fn simple_conversion() {
    println!("=== 简单Markdown转换示例 ===");
    let markdown = "# 简单示例\n\n这是一个*简单*的**Markdown**示例。";
    let html = html::to_html(markdown);
    println!("生成的HTML:\n{}", html);
}

fn file_processing() {
    println!("\n=== 文件处理示例 ===");
    // 写入示例Markdown文件
    fs::write("input/example.md", "# 文件示例\n\n从文件读取的内容").unwrap();
    
    // 读取并转换Markdown文件
    let markdown = fs::read_to_string("input/example.md").unwrap();
    let html = html::to_html(&markdown);
    fs::write("output/example.html", html).unwrap();
    println!("文件已处理并保存到output/example.html");
}

fn custom_options_processing() {
    println!("\n=== 自定义选项处理示例 ===");
    let options = HtmlOptions {
        hard_breaks: true,
        safe_mode: true,
        ..Default::default()
    };
    
    let markdown = "第一行\n第二行\n\n[点击这里]";
    let html = html::to_html_with_options(markdown, &options);
    println!("使用自定义选项生成的HTML:\n{}", html);
}

fn large_file_processing(input_path: &str, output_path: &str) {
    println!("\n=== 大文件处理示例 ===");
    // 创建大示例文件(仅演示，实际应用中应使用已有大文件)
    create_large_markdown_file(input_path);
    
    // 使用缓冲处理大文件
    let input = fs::File::open(input_path).unwrap();
    let reader = BufReader::new(input);
    
    let output = fs::File::create(output_path).unwrap();
    let mut writer = BufWriter::new(output);
    
    html::to_html_buffered(reader, &mut writer).unwrap();
    println!("大文件已处理并保存到{}", output_path);
}

fn create_dir_if_not_exists(dir: &str) {
    if !Path::new(dir).exists() {
        fs::create_dir(dir).unwrap();
    }
}

fn create_large_markdown_file(path: &str) {
    if Path::new(path).exists() {
        return;
    }
    
    let mut content = String::new();
    for i in 1..=1000 {
        content.push_str(&format!("# 标题 {}\n\n", i));
        content.push_str(&format!("这是第{}节的内容。\n\n", i));
    }
    
    fs::write(path, content).unwrap();
}

对应的Cargo.toml配置：

[package]
name = "my_markdown_app"
version = "0.1.0"
edition = "2021"

[dependencies]
md2 = "0.1.0"

运行项目前，请确保项目目录结构如下：

my_markdown_app/
├── Cargo.toml
├── src/
│   ├── main.rs
├── input/
│   ├── example.md
│   └── large.md (运行时会自动创建)
└── output/
    └── (生成的HTML文件)