NaraForm

NaraForm 支援用 Markdown 定義問卷，適合手動撰寫、AI 生成、版本管理，或透過 API 以 Content-Type: text/markdown 更新草稿。

在 Builder 使用 Markdown

在 Builder 上方切換到「Markdown」模式即可直接編輯。右側預覽會依照游標所在題目同步，左側元件模式建立的題目也會自動序列化成 Markdown。

建議流程：

先用「套用範例」或插入題目按鈕建立骨架。
每題補上穩定的 key，例如 department、overall_score。
使用 - value::顯示文字 固定選項 value，避免日後分析欄位變動。
儲存草稿後先看右側預覽，再進行發布前檢查。

基本格式

# 問卷標題
description: 問卷描述（選填）
mode: immersive
theme: nord
completionRedirectUrl: /
completionButtonLabel: 返回首頁

## 問題一的標題
type: single-choice
required: true
key: q1
- value_a::選項 A
- value_b::選項 B

## 問題二的標題
type: short-text
required: false
key: q2
placeholder: 請輸入你的回答
maxLength: 200

## 隱藏 metadata 欄位
type: short-text
required: false
hidden: true
key: source_page

問卷欄位

問卷欄位放在 # 標題下方。

欄位	必填	預設值	說明
`description`	否	空白	問卷描述
`mode`	否	`immersive`	填答模式：`immersive`（單題一頁）或 `scroll`（一頁式）
`theme`	否	`nord`	可用值：`nord`、`pastel`、`abyss`、`cupcake`、`lofi`、`forest`
`completionRedirectUrl`	否	`/`	完成頁按鈕連結；明確留空時不顯示完成頁按鈕
`completionButtonLabel`	否	`返回首頁`	完成頁按鈕文字

題目欄位

每個題目用 ## 標題開始。

欄位	必填	預設值	說明
`type`	是	無	`single-choice`、`multiple-choice`、`short-text`、`long-text`、`rating`
`required`	否	`false`	是否必填
`hidden`	否	`false`	是否隱藏於公開問卷。隱藏題目仍保留在 schema，可用該題 `key` 從 URL query / metadata payload 收集 metadata；後台使用題目標題作為欄位名稱
`key`	否	由題目標題產生	建議使用穩定的 snake_case，方便 API、AI 和資料分析引用
`placeholder`	否	空白	適用於 `short-text`、`long-text`
`maxLength`	否	無	適用於 `short-text`、`long-text`
`minSelect`	否	無	適用於 `multiple-choice`
`maxSelect`	否	無	適用於 `multiple-choice`
`scaleMin`	否	`1`	適用於 `rating`
`scaleMax`	否	`5`	適用於 `rating`，最大值建議不超過 10

選項格式

single-choice 和 multiple-choice 使用 - 列表定義選項。

## 你目前的部門是？
type: single-choice
key: department
- engineering::工程部
- design::設計部
- product::產品部
- other::其他

- 選項文字 會自動產生 value
- value::選項文字 會使用指定 value，適合需要穩定資料鍵的表單

隱藏題目與 Metadata

若某些欄位只需要由 URL query 帶入，不要顯示給受訪者，請把它做成一般題目並加上 hidden: true。

## 來源頁面
type: short-text
required: false
hidden: true
key: source_page

公開問卷 /s/feedback?source_page=guide 不會顯示「來源頁面」這題；送出後，source_page=guide 會存入 response metadata。只有表單 schema 裡已設定為 hidden: true 的題目 key 會被保存。

題型速查

單選題

## 請問您的部門？
type: single-choice
required: true
key: department
- general_management::總管理處
- technology::技術處
- marketing::市場營銷處
- other::其他

多選題

## 目前是否已有可提供參考的內容？
type: multiple-choice
required: false
key: reference_materials
minSelect: 0
maxSelect: 3
- prompt::Prompt
- test_data::測試資料
- expected_output::預期輸出範例
- demo::Demo 畫面

短答與長答

## 姓名
type: short-text
required: true
key: name
placeholder: 請填寫中文全名
maxLength: 80

## 這個服務想解決什麼問題？
type: long-text
required: true
key: problem_statement
placeholder: 請說明目前痛點、現在怎麼處理，以及希望 AI 帶來的價值
maxLength: 1200

評分題

## 整體可行性評分
type: rating
required: true
key: feasibility_score
scaleMin: 1
scaleMax: 5

完整範例

# 員工滿意度問卷
description: 每季員工滿意度調查，約 5 分鐘完成
mode: immersive
theme: nord

## 你目前的部門是？
type: single-choice
required: true
key: department
- engineering::工程部
- design::設計部
- product::產品部
- other::其他

## 對公司整體滿意度評分
type: rating
required: true
key: overall_satisfaction
scaleMin: 1
scaleMax: 10

## 你最滿意的地方是？
type: multiple-choice
key: satisfaction_aspects
minSelect: 1
maxSelect: 3
- 薪資福利
- 工作環境
- 團隊文化
- 成長機會

## 有什麼想對管理層說的？
type: long-text
key: feedback
placeholder: 任何建議或想法都歡迎
maxLength: 1000

API 使用

更新草稿時，將 body 設為 Markdown，並帶上 Content-Type: text/markdown。

curl -X PUT https://YOUR_DOMAIN/api/forms/FORM_ID/version/draft \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: text/markdown" \
  --data-binary @form.md

取得 Markdown 格式草稿時，在 Accept header 指定 text/markdown。

curl https://YOUR_DOMAIN/api/forms/FORM_ID/version/draft \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/markdown"

AI 生成提示

可以直接要求 AI：

請用 NaraForm Markdown 格式建立一份「產品回饋」問卷，包含 8 題，題型涵蓋單選、多選、評分、短答與長答。請為每題提供穩定的 snake_case key。

Markdown 格式

On this page