Md2Form engine documentation

md2form - Markdown to Form Parser

4 min read

md2form

Markdownでフォーム定義を記述し、型安全なJSONに変換するパーサーライブラリ

md2formは、シンプルなMarkdownの記法を使って複雑なWebフォームの構造を定義し、TypeScriptで型安全に扱えるJSONオブジェクトに変換するライブラリです。見出しレベルでページ構造と質問を表現し、ハッシュ記法（#key value）で詳細設定を行います。

✨ 主な特徴

  • 🎯 シンプルな記法: Markdownの見出しと段落だけでフォーム構造を定義
  • 🔒 型安全: TypeScriptの型定義（FormDocument）で変換結果を安全に扱える
  • 📝 豊富な質問タイプ: テキスト入力から評価スケール、ファイルアップロードまで幅広くサポート
  • ⚙️ フロントマター対応: YAMLでフォーム全体の設定を管理
  • 🚀 軽量: 最小限の依存関係で高速動作

🚀 クイックスタート

インストール

npm install md2form
# または
bun add md2form

基本的な使い方

import { parseMarkdownToForm } from "md2form"
import type { FormDocument } from "md2form"
 
const markdown = `
---
collectEmail: true
showProgressBar: true
---
 
# お問い合わせフォーム
簡単なアンケートです。
 
## 基本情報
### お名前
#type short_text
#placeholder "山田 太郎"
#required true
 
### 年齢
#type number
#min 0
#max 120
`
 
const form: FormDocument = await parseMarkdownToForm(markdown)
console.log(form.title) // "お問い合わせフォーム"
console.log(form.pages[0].elements[0].type) // "short_text"

型定義の活用:

import type { ShortText, NumberField } from "md2form"
 
// 型安全なアクセス
form.pages.forEach((page) => {
  page.elements.forEach((element) => {
    if (element.type === "short_text") {
      const shortText = element as ShortText
      console.log(shortText.placeholder)
    }
  })
})

📖 ドキュメント

🎯 サポートされる質問タイプ

カテゴリ質問タイプ説明
テキスト入力short_text, long_text, email, phone各種テキスト入力フィールド
数値入力number数値専用の入力フィールド
選択dropdown, radio, checkbox単一選択・複数選択
日時date, time日付・時刻選択
評価・スケールrating, likert, matrix, scale星評価、リッカート尺度、マトリクス
ファイルfile_upload, signatureファイルアップロード、電子署名
メディアimage, video画像・動画表示
その他boolean, section_headerYes/No選択、セクション見出し

🏗️ 基本的な構造

md2formのMarkdownスキーマは階層構造になっています：

---
# フロントマター（フォーム全体の設定）
collectEmail: true
showProgressBar: true
---
 
# フォームタイトル（必須）
 
フォームの説明文
 
## セクション1（ページ）
 
セクションの説明
 
### 質問1
 
#type short_text
#required true
 
### 質問2
 
#type radio
#options "選択肢1","選択肢2","選択肢3"
 
## セクション2
 
### 質問3
 
#type number
#min 1
#max 10

🔧 開発・貢献

# プロジェクトのクローンと依存関係インストール
git clone <repository>
cd md2form
bun install
 
# サンプルの実行
bun run workspace
 
# 型チェック
bun run tsc --noEmit

📄 ライセンス

MIT License

Get Started →

Graph View