mdstr - Markdown to JSON-safe String#

Zero-config CLI for converting markdown to a JSON-safe string. Pass a file or pipe stdin, get a properly escaped JSON string on stdout. No flags required.

Prerequisites#

Ensure mdstr is available:

bash

# Check if installed
which mdstr

# Install globally if needed
npm install -g mdstr

# Or use npx for one-off conversions
npx mdstr <file>

Requires Node.js 20 or later.

Basic Usage#

From a file#

bash

mdstr README.md
mdstr ./docs/guide.md

From stdin#

bash

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

The output 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#

FlagDescription--preserve-newlineKeep trailing newline in output (stripped by default)--versionShow version number--helpShow help with examples

Exit Codes#

CodeMeaning0Success1Read/conversion error2Invalid usage (file not found, no input)

Common Workflows#

Convert a markdown file to a JSON-safe string#

bash

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:

bash

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

Inject markdown into LLM prompts#

bash

SYSTEM_PROMPT=$(mdstr system-prompt.md)
curl -s https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d "$(jq -n --argjson prompt "$SYSTEM_PROMPT" '{
    model: "gpt-4o",
    messages: [{role: "system", content: $prompt}]
  }')"

Build payloads from multiple markdown files#

bash

jq -n \
  --argjson system "$(mdstr system.md)" \
  --argjson user "$(mdstr user-prompt.md)" \
  '{messages: [{role: "system", content: $system}, {role: "user", content: $user}]}'

Pipe markdown into JSON#

bash

echo '- line 1
- line 2' | mdstr | jq '{content: .}'
# → {"content": "- line 1\n- line 2"}

Keep trailing newline#

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

bash

mdstr README.md --preserve-newline

Output Characteristics#

The output 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. Designed for automated pipelines and agent tool calls.

Error Handling#

When conversion fails, check:

1. File exists and is readable
2. Input is provided (either a file argument or piped stdin)
3. Node.js 20 or later is installed

Errors are printed to stderr with actionable context.

Use Cases#

API payloads#

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

bash

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

LLM prompt construction#

Convert system 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 pipelines#

Convert release notes or changelogs from markdown to JSON-safe strings for automated notifications or API integrations.