Md2Form engine documentation

Markdown Schema

5 min read

Markdown Schema

md2form extends standard Markdown syntax to allow intuitive form structure definition. This page explains the syntax and rules for form definition.

Basic Structure

md2form Markdown follows this hierarchical structure:

---
# Frontmatter (form-wide settings)
---
 
# Form Title (required)
 
Form description (optional)
 
## Section 1 (page)
 
Section description (optional)
 
### Question 1
 
Question description (optional)
 
#type question_type
#property value
 
### Question 2
 
#type another_type
#property1 value1
#property2 value2
 
## Section 2
 
### Question 3
 
#type yet_another_type

Structure Rules

1. Frontmatter (optional)

Form-wide settings can be specified in YAML format at the beginning of the file:

---
collectEmail: true
allowMultipleResponses: false
showProgressBar: true
shuffleQuestions: false
themeColor: blue
responseReceipt: whenRequested
---

2. Form Title (required)

The first # heading becomes the form’s title:

# Customer Satisfaction Survey

3. Form Description (optional)

The paragraph immediately after the form title becomes the form description:

# Customer Satisfaction Survey
 
This survey is intended to gather your feedback
to help us improve our service.

4. Sections (pages)

Create new sections (pages) using ## heading:

## Basic Information Section
 
Please provide your basic information.
 
## Satisfaction Rating Section
 
Please rate each item.

5. Question Definition

Define questions using ### heading:

### Please enter your name
 
Enter your full name.
 
#type short_text
#placeholder "John Doe"
#required true

Question Structure

  • Question Label (label): Content of ### heading (stored in label field in v2)
  • Question Description (description) (optional): Paragraph text immediately after the heading
  • Properties: Specified in #key value format

v2 Changes: In v1, the question title was stored in the description field, but in v2 it is stored in the label field.

Property Syntax

Detailed question settings are specified using the #key value format.

Basic Property Syntax

### Question Label
 
#type short_text
#required true
#placeholder "Example input"
#maxLength 100

Value Types

String Values

#placeholder "Enter text"
#type short_text

Numbers

#min 0
#max 100
#scale 5

Booleans

#required true
#visible false
#allowOther true

Arrays (comma-separated)

#options "Choice 1","Choice 2","Choice 3"
#allowedTypes "pdf","docx","jpg"

Special Notation

Label pairs:

#labels "Low","High"
#scaleLabels "Strongly Disagree","Somewhat Disagree","Neutral","Agree","Strongly Agree"

Complete Example

The following is a complete form definition including all elements:

---
collectEmail: true
allowMultipleResponses: false
showProgressBar: true
shuffleQuestions: false
themeColor: blue
backgroundImage: mountain
responseReceipt: whenRequested
---
 
# Comprehensive Survey Form
 
This survey gathers your profile and feedback
about our service.
 
## Basic Information Section
 
Please provide your basic information first.
 
### Your Name
 
Enter your full name.
 
#type short_text
#placeholder "John Doe"
#required true
#maxLength 50
 
### Self-Introduction
 
Please briefly introduce yourself.
 
#type long_text
#placeholder "Tell us about your hobbies or skills"
#maxLength 500
 
### Age
 
#type number
#min 0
#max 120
#required true
 
### Gender
 
#type dropdown
#options "Male","Female","Other","Prefer not to say"
#required false
 
## Rating Section
 
Please rate our service.
 
### Overall Satisfaction
 
#type rating
#scale 5
#labels "Dissatisfied","Very Satisfied"
#required true
 
### Item Rating
 
Please rate each item on a 5-point scale.
 
#type likert
#statements "Product quality","Price fairness","Staff service","Store atmosphere"
#scaleLabels "Very Poor","Poor","Average","Good","Very Good"
#requiredPerStatement true
 
### Areas for Improvement
 
#type checkbox
#options "Increase product variety","Lower prices","Extend hours","Expand parking","Other"
#maxSelected 3
 
## Additional Information Section
 
### Visit Frequency
 
#type radio
#options "More than weekly","2-3 times monthly","Once monthly","A few times yearly","First visit"
#allowOther false
 
### Feedback
 
#type long_text
#placeholder "Feel free to write"
#maxLength 1000
 
### Contact Preference
 
May we send you special offers?
 
#type boolean
#onLabel "Yes, send offers"
#offLabel "No thank you"

Notation Best Practices

1. Heading Level Consistency

# Form Title (Level 1: one only)
 
## Section Title (Level 2: multiple allowed)
 
### Question Label (Level 3: multiple allowed)

Place related properties close together:

### Age Input
 
#type number
#min 0
#max 120
#step 1
#required true
#placeholder "Enter age"

3. Clear Labels

# ❌ Poor example
 
### Name
 
#type short_text
 
# ✅ Good example
 
### Please enter your name
 
#type short_text
#placeholder "John Doe"

4. Using Descriptions

### Credit Card Number
 
Enter the credit card number used for payment.
The entered information is encrypted and processed securely.
 
#type short_text
#placeholder "1234-5678-9012-3456"
#required true

Restrictions and Important Notes

1. Heading Levels

  • # heading: Form title (one only)
  • ## heading: Section separator
  • ### heading: Question definition
  • #### and below: Not currently supported

2. Property Placement

Properties must be placed in the paragraph immediately after a question (### heading):

# ❌ Incorrect
 
### Question
 
Question description
 
Another paragraph
 
#type short_text # Not recognized here
 
# ✅ Correct
 
### Question
 
Question description
 
#type short_text
#required true

3. Quoting Values

Properly escape values containing commas:

#options "Choice 1","Choice 2, note","Choice 3"

4. Property Name Case

Property names must be lowercase:

# ❌ Incorrect
 
#Type short_text
#Required true
 
# ✅ Correct
 
#type short_text
#required true

Next Steps

After understanding the schema, check the following pages to learn specific question types and properties:

Graph View

Backlinks