mdforge

mdforge は、拡張 Markdown を定義してから扱うための Rust ライブラリです。
LLM が生成したテキストを、型付き引数・構文ルール・診断情報で安全に扱い、DOM 風の中間表現 (VNode) へ変換できます。

特徴

• 拡張ブロック / インライン構文を ForgeBuilder で宣言
• 引数型 (Int / String / StaticEnum / DynamicEnum) を定義して検証
• parse -> validate -> eval -> render_dom のパイプライン API
• Diagnostic (ErrorCode, Span, suggestion) によるエラー収集
• LLM 指示向けの仕様文字列 (signature) を生成

インストール

Cargo.toml に追加してください。

[dependencies]
mdforge = "0.1.0"

クイックスタート

use mdforge::{ArgType, EvalContext, Forge, VNode};

let forge = Forge::builder()
    .block("card")
    .arg("title", ArgType::String.required())
    .arg("level", ArgType::Int.optional())
    .body_markdown()
    .register()
    .inline("badge")
    .arg("level", ArgType::Int.required())
    .register()
    .build();

let input = ":::card title=hello level=1\ntext {badge level=2}\n:::\n";

let doc = forge.parse(input).expect("parse");
forge.validate(&doc).expect("validate");
let ctx = forge.eval(&doc, &EvalContext::default()).expect("eval");

struct NoopRenderer;
impl mdforge::forge::DomRenderer for NoopRenderer {
    fn render_block(
        &self,
        _block: &mdforge::BlockNode,
        _ctx: &EvalContext,
        children: Vec<VNode>,
    ) -> VNode {
        VNode::Text(format!("block children={} ", children.len()))
    }

    fn render_inline(&self, _inline: &mdforge::InlineExt, _ctx: &EvalContext) -> VNode {
        VNode::Text("inline".to_string())
    }
}

let nodes = forge
    .render_dom(&doc, &ctx, &NoopRenderer)
    .expect("render_dom");

println!("nodes: {}", nodes.len());
println!("signature:\n{}", forge.signature());

主要 API

• Forge::builder() / ForgeBuilder
• Forge::parse
• Forge::validate
• Forge::eval
• Forge::render_dom
• Forge::signature

テスト

通常のテストは外部 API に接続せず、OpenAI 連携部分もモックで検証します。

cargo test

実際に OpenAI API へ 1 回だけリクエストするライブテストは、明示的に有効化した場合だけ実行されます。

OPENAI_API_KEY=... MDFORGE_RUN_OPENAI_TESTS=1 cargo test ai_pipeline_can_call_openai_when_enabled --test openai_pipeline

モデルは既定で gpt-4.1-mini を使います。必要なら OPENAI_MODEL で変更できます。

デモ Web アプリ

料理レシピ生成デモの Recipe Lab を起動できます。

cargo run --example recipe_lab

ブラウザで http://127.0.0.1:3000 を開くと、手入力した mdforge Markdown を HTML プレビューできます。OpenAI 生成も試す場合は、.env に API キーを設定してから起動してください。

OPENAI_API_KEY=...

Recipe Lab では、recipe / step / tip ブロックと、ingredient / needed / timer / badge インラインを使います。各 step には必須の minutes、各食材マークアップには必須の amount を持たせ、食材参照は DynamicEnum("ingredients") で検証します。

詳しい使い方は以下を参照:

• docs/user_guide.md
• docs/design_v0.1.md

ライセンス

このプロジェクトは MIT License のもとで提供されます。