yorick-ryu/md2docx-skill/md2docx

md2docx - Markdown to Word Converter

Convert Markdown text to professionally formatted Word (DOCX) documents.

Quick Start

Default to file mode for local skill execution:

# File mode: Saves file directly (default for local environments)
python scripts/convert.py input.md
 
# URL mode: Returns download URL when running remotely
python scripts/convert.py input.md --url

Choosing the Right Mode

Decision Rule:

• Run without a mode flag when the skill runs on the same machine where the user wants the output file.
• Use --url only when the skill runs in a different environment than the user (cloud, remote server, MCP server).

How It Works

1. Prepare Markdown: Ensure content is in standard Markdown format
2. Run Script: Execute scripts/convert.py with appropriate mode
3. Get Result:

• URL mode: Receive download URL
• File mode: File saved to specified location

API Details

Endpoints:

• URL mode: https://api.deepshare.app/convert-text-to-url → Returns {"url": "..."}
• File mode: https://api.deepshare.app/convert-text → Returns DOCX file directly

Authentication: Set the DEEP_SHARE_API_KEY environment variable and send it as X-API-Key.

API Key Configuration

Set the environment variable before running the skill:

export DEEP_SHARE_API_KEY="your_api_key_here"

The skill reads only this environment variable. If it is missing, conversion stops with a configuration error.

Request Format

{
  "content": "markdown text here",
  "filename": "output",
  "template_name": "templates",
  "language": "zh"
}

Parameters

Common Templates

Chinese (language: "zh"):

• templates - General purpose
• 论文 - Academic paper
• 论文-首行不缩进 - Paper without indent
• 论文-标题加粗 - Paper with bold headings

English (language: "en"):

• templates - General purpose
• article - Article/report style
• thesis - Academic thesis

Conversion Script Usage

Command Line Options

python scripts/convert.py <input.md> [options]
 
Options:
  --url              Return download URL
  --file             Save file directly to disk (default if no mode specified)
  --template, -t     Template name (default: templates)
  --language, -l     Language: zh or en (default: zh)
  --filename         Output filename without .docx (default: input basename)
  --output, -o       Output directory for file mode

Examples

# File mode (local environments, default)
python scripts/convert.py document.md
python scripts/convert.py paper.md --file --output ./docs --template thesis --language en
python scripts/convert.py notes.md --file --filename meeting-notes
 
# URL mode (cloud/remote environments)
python scripts/convert.py document.md --url
python scripts/convert.py paper.md --url --template 论文 --language zh

Validation Before Conversion

Ensure Markdown content:

• Headers use # syntax
• Lists use - or 1. syntax
• Code blocks use triple backticks
• Math formulas use $...$ (inline) or $$...$$ (block)
• Images use publicly accessible URLs

Response Handling

URL Mode Response

Success (200 OK):

{
  "url": "https://flies.deepshare.app/mcp/hash/document_xxx.docx"
}

File Mode Response

Success: File saved to disk, path printed to stdout

Error Responses (Both Modes)

• 401 Unauthorized - Invalid API key
• 403 Forbidden - Quota exceeded → Purchase at https://ds.rick216.cn/purchase
• 413 Payload Too Large - Content exceeds 10MB
• 500 Internal Server Error - Service unavailable, retry

User Communication

On Success

Tell user:

1. Conversion completed successfully
2. URL mode: Provide the download URL
3. File mode: Provide the file path where document was saved
4. Check which API key was used:

• If using the environment variable: No reminder needed
• If the environment variable is missing: Tell the user to set DEEP_SHARE_API_KEY

On Quota Exceeded

Tell user:

1. Conversion failed: quota exceeded
2. Purchase more credits at: https://ds.rick216.cn/purchase
3. Recheck DEEP_SHARE_API_KEY

On Other Errors

Tell user:

1. What went wrong (based on error message)
2. How to fix it
3. Offer to retry

Tips

• API Key Configuration:
• Set environment variable DEEP_SHARE_API_KEY

``bash export DEEP_SHARE_API_KEY="your_api_key_here" ``

• File Size: Keep Markdown under 10MB
• Images: Use https:// URLs, not local paths
• Math: Use LaTeX syntax: $E=mc^2$ or $$\int_0^\infty$$
• Templates: Choose based on document type (paper, article, etc.)

Example Workflows

Workflow 1: Cloud Environment (URL Mode)

User asks: "Convert this to Word" (skill running in cloud)

1. Save the Markdown content to a temporary file (e.g., temp.md)

1. Run the conversion script with URL mode:

``bash python scripts/convert.py temp.md --url ``

1. The script will:

• Read the API key from DEEP_SHARE_API_KEY
• Call the conversion API
• Return download URL

1. Provide the download URL to user

1. Clean up temporary file

Workflow 2: Local Environment (File Mode)

User asks: "Convert my notes.md to Word" (skill running locally)

1. Run the conversion script with file mode:

``bash python scripts/convert.py notes.md --output ./output ``

1. The script will:

• Read the API key from DEEP_SHARE_API_KEY
• Call the conversion API
• Save the DOCX file directly

1. Tell user where the file was saved

1. No cleanup needed - file is the output