Md2Form engine documentation

Frontmatter Settings

5 min read

Frontmatter Settings

Frontmatter is YAML format configuration written at the beginning of a Markdown file that applies to the entire form. This page describes all available frontmatter settings in detail.

Basic Usage

Frontmatter is written at the beginning of a Markdown file, enclosed with ---:

---
collectEmail: true
allowMultipleResponses: false
showProgressBar: true
---
 
# Form Title
 
Form content...

Configuration Options

collectEmail

Description: Sets whether to collect email addresses when responding to forms.

Type: boolean

Default: false

---
collectEmail: true
---

When this setting is true:

  • Respondents are required to enter an email address
  • Response management and tracking becomes easier
  • Follow-up email sending becomes possible

allowMultipleResponses

Description: Sets whether to allow multiple responses from the same user.

Type: boolean

Default: true

---
allowMultipleResponses: false
---

Value meanings:

  • true: Users can respond multiple times
  • false: Users can respond only once

limitResponses

Description: Sets the maximum number of responses for the entire form.

Type: number | null

Default: null (no limit)

---
limitResponses: 100
---

Examples:

  • 100: Response collection ends at 100 responses
  • null or not set: No limit on responses

showProgressBar

Description: Sets whether to display a progress bar in multi-page forms.

Type: boolean

Default: false

---
showProgressBar: true
---

When this setting is true:

  • Form progress is displayed visually
  • Users can understand the estimated completion time
  • User experience is improved

shuffleQuestions

Description: Sets whether to randomly change the order of questions.

Type: boolean

Default: false

---
shuffleQuestions: true
---

Usage scenarios:

  • When you want to reduce bias in survey research
  • When you want to eliminate question order effects
  • When conducting A/B testing

responseReceipt

Description: Specifies response receipt notification settings.

Type: "always" | "never" | "whenRequested"

Default: "whenRequested"

---
responseReceipt: always
---

Value meanings:

  • "always": Always send receipt notification
  • "never": Do not send receipt notification
  • "whenRequested": Send only when user requests

Theme Settings

Settings for customizing form appearance.

themeColor

Description: Sets the main color of the form.

Type: string

Default: System default

---
themeColor: blue
themeColor: "#3B82F6"
themeColor: "rgb(59, 130, 246)"
---

Allowed values:

  • Color names: blue, red, green, purple, etc.
  • HEX codes: #3B82F6, #EF4444, etc.
  • RGB values: rgb(59, 130, 246), etc.

backgroundImage

Description: Sets the background image of the form.

Type: string

Default: None

---
backgroundImage: mountain
backgroundImage: "https://example.com/background.jpg"
---

Specification methods:

  • Preset names: mountain, ocean, forest, city, etc.
  • URL: Direct image file URL
  • Relative path: Path to local image file

font

Description: Sets the font family used in the form.

Type: string

Default: System default

---
font: "Noto Sans JP"
font: "Arial, sans-serif"
---

Complete Configuration Example

Here is a complete example with all settings:

---
# Response collection settings
collectEmail: true
allowMultipleResponses: false
limitResponses: 500
 
# UI/UX settings
showProgressBar: true
shuffleQuestions: false
 
# Notification settings
responseReceipt: whenRequested
 
# Theme settings
themeColor: "#2563EB"
backgroundImage: mountain
font: "Noto Sans JP, sans-serif"
---

Practical Configuration Patterns

Pattern 1: General Survey

---
collectEmail: true
allowMultipleResponses: false
showProgressBar: true
responseReceipt: whenRequested
themeColor: blue
---
  • Collect email addresses
  • Prevent duplicate responses
  • Display progress
  • Send receipt only if requested

Pattern 2: Ongoing Research

---
collectEmail: false
allowMultipleResponses: true
showProgressBar: false
shuffleQuestions: true
responseReceipt: never
---
  • Anonymous responses
  • Allow multiple responses
  • Randomize question order
  • No notifications

Pattern 3: Limited Recruitment Form

---
collectEmail: true
allowMultipleResponses: false
limitResponses: 100
showProgressBar: true
responseReceipt: always
themeColor: "#DC2626"
---
  • Email address required
  • Closes at 100 responses
  • Always send receipt notification
  • Red theme to convey urgency

Pattern 4: Corporate Branding Priority

---
collectEmail: true
allowMultipleResponses: false
showProgressBar: true
responseReceipt: whenRequested
themeColor: "#1F2937"
backgroundImage: "https://company.com/bg.jpg"
font: "Corporate Font, Arial, sans-serif"
---
  • Use corporate colors
  • Custom background and font
  • Unified brand image

Configuration Application Priority

  1. Frontmatter settings - Highest priority
  2. Default values - For items not specified in frontmatter

Notes on Configuration

1. YAML Syntax Compliance

# ❌ Incorrect
---
collectEmail = true
showProgressBar: "true"
---
 
# ✅ Correct
---
collectEmail: true
showProgressBar: true
---

2. Boolean Value Specification

# ❌ Incorrect
allowMultipleResponses: "false"
showProgressBar: 0
 
# ✅ Correct
allowMultipleResponses: false
showProgressBar: true

3. String Quoting

Enclose strings with special characters or spaces in quotes:

# Basic string
themeColor: blue
 
# With special characters
font: "Noto Sans JP, sans-serif"
backgroundImage: "https://example.com/image with spaces.jpg"

4. Configuration Value Validity

Invalid configuration values are ignored:

---
responseReceipt: invalid_value # Ignored
limitResponses: -1 # Ignored (negative numbers are invalid)
themeColor: "invalid_color" # Ignored
---

TypeScript Type Definition

Frontmatter settings are defined by the following type:

type FormSettings = {
  collectEmail?: boolean
  allowMultipleResponses?: boolean
  limitResponses?: number | null
  showProgressBar?: boolean
  shuffleQuestions?: boolean
  themeColor?: string
  backgroundImage?: string
  font?: string
  responseReceipt?: "always" | "never" | "whenRequested"
}

Dynamic Configuration Changes

Frontmatter settings are determined at parse time, so dynamic changes during form display are not supported. To change settings, update the Markdown file and parse again.

Debugging and Troubleshooting

Settings Not Applied

  1. Verify YAML syntax - Check indentation and syntax
  2. Verify setting values - Ensure values are within valid ranges
  3. Verify type matching - Ensure boolean, number, string types are correct

Common Errors

# ❌ YAML parsing error
---
collectEmail: true
showProgressBar true  # Missing colon
---
 
# ❌ Invalid setting value
---
responseReceipt: sometimes  # Invalid enumeration value
---
 
# ❌ Type mismatch
---
limitResponses: "100"  # Should be number, not string
---

Next Steps

After understanding frontmatter settings, check these pages for more detailed information:

Graph View

Backlinks