# Pandoc Converter

> >

- **Type:** Skill
- **Install:** `agentstack add skill-haiyuan-ai-agent-skills-pandoc-converter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [haiyuan-ai](https://agentstack.voostack.com/s/haiyuan-ai)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [haiyuan-ai](https://github.com/haiyuan-ai)
- **Source:** https://github.com/haiyuan-ai/agent-skills/tree/main/pandoc-converter

## Install

```sh
agentstack add skill-haiyuan-ai-agent-skills-pandoc-converter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Pandoc Document Converter

Convert between Markdown, Word (.docx), HTML, and PDF with proper CJK support out of the box.

## Supported Conversions

| From     | To           |
|----------|--------------|
| Markdown | PDF          |
| Markdown | Word (.docx) |
| Markdown | HTML         |
| Word     | Markdown     |
| Word     | PDF          |
| HTML     | Markdown     |
| HTML     | Word (.docx) |
| HTML     | PDF          |

PDF as input is not supported (pandoc limitation).

---

## Scripts

| Script | Purpose | When to use |
|--------|---------|-------------|
| `convert-to-pdf.sh` | Optimized PDF with CJK monospace font, 11pt, 1.5cm margins | All PDF conversions (recommended) |
| `fix-ascii-art.py` | Pad ASCII box lines to equal width | Before Word conversion if ASCII diagrams exist |

---

## Step-by-step Workflow

### 1. Identify the conversion

From the user's request, determine:
- **Source file(s)**: path and format
- **Target format**: pdf, docx, md, or html
- **Options**: template, styling, batch mode

Verify the source file exists before proceeding.

### 2. Build the pandoc command

Start with the base: `pandoc  -o `

Then layer on options based on the target format.

#### PDF Output

**Recommended: use the conversion script** (includes CJK monospace font, 11pt, optimized margins):
```bash
bash ~/.agents/skills/pandoc-converter/scripts/convert-to-pdf.sh input.md
```

**Manual setup**:
```bash
pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="PingFang SC" \
  -V monofont="Sarasa Fixed SC" \
  -V geometry:margin=2cm
```

**Common variables**:
```bash
-V fontsize=11pt             # 11pt recommended for technical docs
-V linestretch=1.5
-V papersize=a4
-V toc=true
```

📚 **Font details**: [references/fonts.md](references/fonts.md)

#### Word Output

**Recommended workflow**:
```bash
# 1. Fix ASCII art alignment (if needed)
python3 ~/.agents/skills/pandoc-converter/scripts/fix-ascii-art.py input.md --check

# 2. Fix if issues found
python3 ~/.agents/skills/pandoc-converter/scripts/fix-ascii-art.py input.md

# 3. Convert with reference.docx
pandoc input.md -o output.docx \
  --reference-doc=~/.agents/skills/pandoc-converter/references/reference.docx
```

Built-in `reference.docx` includes:
- **CJK font**: 思源黑体 CN (Source Han Sans CN)
- **English font**: Times New Roman
- **Code font**: Sarasa Fixed SC (CJK-aware monospace)
- **Table styles**: Header shading, vertical center alignment

#### Markdown Output

```bash
pandoc input.docx -o output.md --extract-media=./media --wrap=none
```

#### HTML Output

```bash
# Standalone HTML
pandoc input.md -o output.html --standalone

# With CSS
pandoc input.md -o output.html --standalone --css=style.css

# Self-contained (embed images)
pandoc input.md -o output.html --standalone --embed-resources
```

#### HTML Input

```bash
# HTML to Markdown
pandoc input.html -o output.md --wrap=none

# HTML to PDF
pandoc input.html -o output.pdf --pdf-engine=xelatex -V CJKmainfont="PingFang SC"
```

### 3. Handle images and resources

- For markdown with local images: use `--resource-path` if needed
- For Word to Markdown: always use `--extract-media`
- For PDF with images: xelatex handles most formats

### 4. Run and verify

Execute the command. Common issues:

| Issue | Solution |
|-------|----------|
| xelatex not found | `brew install --cask mactex` |
| Font not found | `fc-list :lang=zh` to list available fonts |
| Missing LaTeX package | `tlmgr install ` |

### 5. Batch conversion

Use a for-loop with the same options as single-file conversion:
```bash
for f in *.md; do pandoc "$f" -o "${f%.md}.pdf" --pdf-engine=xelatex -V CJKmainfont="PingFang SC"; done
```

---

## Advanced Features

The following features are documented in separate reference files:

| Feature | Description | Reference |
|---------|-------------|-----------|
| **Font Configuration** | CJK fonts, fallback, code fonts | [references/fonts.md](references/fonts.md) |
| **Syntax Highlighting** | Code themes, language support | [references/syntax-highlighting.md](references/syntax-highlighting.md) |
| **Math** | LaTeX equations, MathJax, KaTeX | [references/math.md](references/math.md) |
| **PDF Features** | Metadata, frontmatter, watermarks | [references/pdf-features.md](references/pdf-features.md) |
| **Advanced** | Citations, multi-file, GFM, Lua filters | [references/advanced.md](references/advanced.md) |

---

## Common Pitfalls

- **Garbled Chinese text in PDF**: Always use `--pdf-engine=xelatex` with a CJK font
- **Word styles look wrong**: Use `--reference-doc` for custom styling
- **Images missing in Markdown output**: Add `--extract-media`
- **PDF margins too tight**: Add `-V geometry:margin=2cm`
- **HTML lacks styles**: Use `--standalone`
- **HTML images not showing**: Use `--embed-resources` to inline images
- **Citations not rendering**: Ensure `--citeproc` is included
- **Math not rendering in HTML**: Add `--mathjax` or `--katex`
- **ASCII art misaligned in Word/PDF**: 
  - Run `python3 ~/.agents/skills/pandoc-converter/scripts/fix-ascii-art.py input.md`
  - Use `convert-to-pdf.sh` which enforces monospace font
- **Code block background shows trailing spaces**: reference.docx has no shading on Source Code style

---

## Output Naming

Unless the user specifies an output path, place the output in the same directory as the input, with the same base name and the new extension.

---

## Safety

- Check if target file exists before overwriting
- Always quote paths in shell commands
- Only read source files and write output; never modify originals

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [haiyuan-ai](https://github.com/haiyuan-ai)
- **Source:** [haiyuan-ai/agent-skills](https://github.com/haiyuan-ai/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-haiyuan-ai-agent-skills-pandoc-converter
- Seller: https://agentstack.voostack.com/s/haiyuan-ai
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.