# Md2docx

> Convert Markdown to Word (DOCX) documents. Use when user wants to export, convert, or create Word documents from Markdown content.

- Skill: `yorick-ryu/md2docx` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add yorick-ryu/md2docx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yorick-ryu/md2docx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: yorick-ryu (https://skillmd.com/u/yorick-ryu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yorick-ryu/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:

```bash
# 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

| Scenario | Mode | Command |
|----------|------|---------|
| Skill runs locally, user wants file saved | file mode | `python scripts/convert.py input.md` |
| Skill runs in cloud, user needs to download | `--url` | `python scripts/convert.py input.md --url` |
| Remote execution (MCP, API, cloud agent) | `--url` | Returns URL for user to download |
| Local execution (user's machine) | file mode | Saves .docx directly to disk |

**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:

```bash
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

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

## Parameters

| Parameter | Default | Description |
|-----------|---------|-------------|
| `content` | required | Markdown text to convert |
| `filename` | `"output"` | Output filename (without .docx) |
| `template_name` | `"templates"` | Template: `templates`, `论文`, `article`, `thesis`, etc. |
| `language` | `"zh"` | Template language: `zh` or `en` |

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

```bash
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

```bash
# 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):
```json
{
  "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`)

2. Run the conversion script with URL mode:
   ```bash
   python scripts/convert.py temp.md --url
   ```

3. The script will:
   - Read the API key from `DEEP_SHARE_API_KEY`
   - Call the conversion API
   - Return download URL

4. Provide the download URL to user

5. 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
   ```

2. The script will:
   - Read the API key from `DEEP_SHARE_API_KEY`
   - Call the conversion API
   - Save the DOCX file directly

3. Tell user where the file was saved

4. No cleanup needed - file is the output