mdstr

mdstr - Markdown to JSON-safe String

Zero-config 命令行工具 for converting markdown to a JSON-safe string. Pass a file or pipe stdin, 获取 a properly escaped JSON string on stdout. No flags required.

Prerequisites

Ensure mdstr is avAIlable:

# 检查 if 安装ed which mdstr

# 安装 globally if needed npm 安装 -g mdstr

# Or use npx for one-off conversions npx mdstr

Requires Node.js 20 or later.

Basic Usage From a file mdstr README.md mdstr ./docs/图形界面de.md

From stdin cat notes.md | mdstr echo '# "Hello" World' | mdstr # → "# \"Hello\" World"

The 输出 is always a single JSON string on stdout, surrounded by quotes, with all special characters properly escaped. Ready to embed directly into JSON structures.

Options Flag Description --preserve-newline Keep trAIling newline in 输出 (stripped by default) --version Show version number --help Show help with examples Exit Codes Code Meaning 0 成功 1 Read/conversion error 2 Invalid usage (file not found, no 输入) Common 工作流s Convert a markdown file to a JSON-safe string mdstr instructions.md # → "# Instructions\n\nDo this and that.\n\nSAId \"hello\" and left."

Embed markdown in a JSON payload

Use jq to build JSON structures with markdown content:

jq -n --argjson content "$(mdstr instructions.md)" '{prompt: $content}' > payload.json

Inject markdown into LLM prompts 系统_PROMPT=$(mdstr 系统-prompt.md) curl -s https://API.openAI.com/v1/chat/completions \ -H "Content-Type: 应用/json" \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -d "$(jq -n --argjson prompt "$系统_PROMPT" '{ 模型: "gpt-4o", messages: [{角色: "系统", content: $prompt}] }')"

Build payloads from multiple markdown files jq -n \ --argjson 系统 "$(mdstr 系统.md)" \ --argjson user "$(mdstr user-prompt.md)" \ '{messages: [{角色: "系统", content: $系统}, {角色: "user", content: $user}]}'

Pipe markdown into JSON echo '- line 1

• line 2' | mdstr | jq '{content: .}'

Keep trAIling newline

By default, mdstr strips the trAIling newline. To preserve it:

mdstr README.md --preserve-newline

输出 Characteristics

The 输出 is always:

A single JSON string on stdout (with surrounding quotes) All special characters escaped (", \, newlines, tabs, etc.) TrAIling newline stripped by default (use --preserve-newline to keep) Errors on stderr Deterministic exit codes

No confirmation prompts. No color codes. No spinners. De签名ed for automated 流水线s and 代理 工具 calls.

Error Handling

When conversion fAIls, 检查:

File exists and is readable 输入 is provided (either a file argument or piped stdin) Node.js 20 or later is 安装ed

Errors are printed to stderr with actionable 上下文.

Use Cases API payloads

Convert markdown documentation or prompts into JSON-safe strings for REST API calls:

mdstr prompt.md # Use the 输出 directly in curl or httpie commands

LLM prompt construction

Convert 系统 prompts, user messages, or few-shot examples stored as markdown files into strings suitable for LLM API payloads.

Configuration files

Embed markdown content (descriptions, help text, documentation) into JSON config files.

CI/CD 流水线s

Convert release notes or change记录s from markdown to JSON-safe strings for automated 通知 or API integrations.