md2form - Markdown to Form Parser

md2form

Parse form definitions written in Markdown and convert to type-safe JSON

md2form is a parser library that uses simple Markdown syntax to define complex web form structures and converts them to TypeScript type-safe JSON objects. Form page structure and questions are expressed by heading levels, and detailed settings are configured using hash notation (#key value).

✨ Key Features

• 🎯 Simple Syntax: Define form structure using only Markdown headings and paragraphs
• 🔒 Type Safe: Handle conversion results safely with TypeScript type definitions (FormDocument)
• 📝 Rich Question Types: Support wide variety from text input to rating scales and file uploads
• ⚙️ Frontmatter Support: Manage entire form settings with YAML
• 🩺 Diagnostic System: Receive parse errors and warnings as structured Diagnostic array
• 🚀 Lightweight: High-speed operation with minimal dependencies

🚀 Quick Start

Installation

npm install md2form
# or
bun add md2form

Basic Usage (v2)

import { parseForm, isParsedDocument } from "md2form"
import type { FormDocument } from "md2form"
 
const markdown = `
---
collectEmail: true
showProgressBar: true
---
 
# Contact Form
Simple survey.
 
## Basic Information
### Your Name
#type short_text
#placeholder "John Doe"
#required true
 
### Age
#type number
#min 0
#max 120
`
 
const result = parseForm(markdown, { strict: true, validateSettings: true })
 
if (!isParsedDocument(result)) {
  console.error(result.diagnostics)
  throw new Error("Invalid form markdown")
}
 
const form: FormDocument = result.document
console.log(form.title) // "Contact Form"
console.log(form.pages[0].elements[0].type) // "short_text"
console.log(form.pages[0].elements[0].label) // "Your Name"

Using Type Definitions:

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)
    }
  })
})

Migrating from v1: parseMarkdownToForm is deprecated in v2. Use parseForm for new code. See API Reference for details.

📖 Documentation

• Getting Started - From installation to basic usage
• Markdown Schema - Form definition syntax and rules
• Question Types - All supported question types
• Property Reference - List of configurable properties
• Frontmatter Settings - Form-wide configuration options
• Type Definitions - TypeScript type definition details
• Examples - Real-world usage and samples
• API Reference - Functions and classes details

🎯 Supported Question Types

Category	Question Types	Description
Text Input	short_text, long_text, email, phone	Various text input fields
Number Input	number	Numeric input field
Selection	dropdown, radio, checkbox	Single/multiple selection
Date/Time	date, time	Date and time selection
Rating/Scale	rating, likert, matrix, scale	Star rating, Likert scale, matrix
File	file_upload, signature	File upload, digital signature
Media	image, video	Image and video display
Other	boolean, section_header	Yes/No selection, section heading

🏗️ Basic Structure

md2form Markdown schema has a hierarchical structure:

---
# Frontmatter (form-wide settings)
collectEmail: true
showProgressBar: true
---
 
# Form Title (required)
 
Form description
 
## Section 1 (page)
 
Section description
 
### Question 1
 
#type short_text
#required true
 
### Question 2
 
#type radio
#options "Option 1","Option 2","Option 3"
 
## Section 2
 
### Question 3
 
#type number
#min 1
#max 10

🔧 Development and Contribution

# Clone project and install dependencies
git clone <repository>
cd md2form
bun install
 
# Run samples
bun run workspace
 
# Run tests
bun test
 
# Type checking
bun run typecheck

📄 License

MIT License

---

Get Started →