doc-converter

name	doc-converter
version	1.0.0
description	Convert between document formats — Markdown to HTML, DOCX to PDF, CSV to JSON, and more. Uses pandoc and Python libraries for reliable, high-quality conversions. Use this skill when the user needs to: convert a file to another format, export a document, change file types, or says "convert this to PDF", "turn this into HTML", "export as CSV." Also trigger for "convert", "export", "pandoc", "format conversion", or when output needs to be in a different format than input.
author	G-HunterAi
license	MIT
tags	["conversion","documents","pandoc","export","formats"]
platforms	["all"]
category	tooling
metadata	{"clawdbot":{"emoji":"🔄","requires":{"bins":["pandoc","python3"]}}}

Document Converter Skill

Universal document format conversion using pandoc as the primary engine with Python libraries as fallback. Supports Markdown, HTML, DOCX, PDF, CSV, JSON, XML, and more.

When to Use / When NOT to Use

Use for:

• Format conversion (Markdown → HTML, DOCX → PDF, CSV → JSON)
• Batch converting multiple files across formats
• Template-based document export with formatting preservation
• Converting structured data between formats

NOT for:

• Creating documents from scratch (write directly in target format)
• Filling PDF forms (use pdf-form-filler)
• Video/audio conversion (use ffmpeg-video-editor)

Quick Start

Markdown to HTML

from doc_converter import convert_document

result = convert_document(
    input_file="article.md",
    output_format="html",
    output_file="article.html"
)
print(f"Converted: {result.output_path}")

DOCX to PDF

from doc_converter import convert_document

result = convert_document(
    input_file="report.docx",
    output_format="pdf",
    output_file="report.pdf",
    preserve_formatting=True
)

CSV to JSON

from doc_converter import convert_document

result = convert_document(
    input_file="data.csv",
    output_format="json",
    output_file="data.json"
)

HTML to Markdown

from doc_converter import convert_document

result = convert_document(
    input_file="webpage.html",
    output_format="markdown",
    output_file="webpage.md",
    clean_output=True
)

Features

1. Extensive Format Support

Support for 30+ document formats with smart detection of input/output types.

2. Quality Preservation

• Formatting preservation (bold, italics, headers, lists)
• Image embedding and reference handling
• Metadata and properties conservation
• Layout and style options for PDF

3. Batch Conversion

Convert multiple files in parallel with progress tracking.

4. Smart Defaults

• Auto-detect input format from file extension
• Intelligent output naming
• Sensible default options per format pair

5. Advanced Options

convert_document(
    input_file="document.md",
    output_format="pdf",
    options={
        "pdf_engine": "wkhtmltopdf",      # or "weasyprint"
        "margin": "1cm",
        "font_size": "12pt",
        "include_toc": True,               # Table of contents
        "number_sections": True
    }
)

Conversion Matrix

From	To	Quality	Speed	Notes
MD	HTML	Excellent	Fast	Markdown tables preserved
MD	PDF	Excellent	Medium	Requires pandoc
MD	DOCX	Good	Fast	Styling optional
HTML	MD	Good	Fast	Requires HTML cleaner
HTML	PDF	Good	Medium	JavaScript-heavy sites problematic
DOCX	PDF	Excellent	Medium	Preserves formatting
DOCX	HTML	Good	Fast	Tables and lists preserved
DOCX	MD	Good	Medium	Some formatting lost
PDF	MD	Fair	Slow	Requires OCR for images
PDF	HTML	Fair	Slow	Layout may shift
CSV	JSON	Excellent	Fast	Schema inference
CSV	XLSX	Excellent	Fast	Type detection
JSON	CSV	Good	Fast	Flattens nested structures
JSON	XML	Good	Fast	Element naming configurable
XML	JSON	Good	Fast	Attribute handling
XML	CSV	Fair	Medium	Requires schema

Use Cases

Case 1: Blog to Newsletter

User: "Convert this blog post to a newsletter-friendly format"
→ Input: blog-post.md
→ Convert to HTML (for email)
→ Strip code blocks or simplify
→ Output: newsletter.html

Case 2: Data Export

User: "Export this spreadsheet as JSON for the API"
→ Input: data.xlsx
→ Detect columns and types
→ Convert to JSON with schema
→ Output: data.json

Case 3: Documentation Generation

User: "Generate PDFs from my markdown documentation"
→ Input: docs/*.md
→ Batch convert to PDF
→ Include table of contents
→ Numbered sections
→ Output: docs/*.pdf

Case 4: Content Repurposing

User: "Turn this DOCX into a web page"
→ Input: proposal.docx
→ Convert to HTML
→ Preserve images
→ Add basic CSS styling
→ Output: proposal.html

Case 5: Data Format Alignment

User: "Convert CSV to XML for our legacy system"
→ Input: inventory.csv
→ Parse CSV with headers
→ Generate XML with proper structure
→ Output: inventory.xml

Works Well With

• pdf-form-filler — Convert filled forms to other formats for archival/sharing
• in-depth-research — Export research documents to any format (PDF, HTML, DOCX)
• data-analysis — Convert between CSV, JSON, XML, and Excel formats
• translation — Translate documents first, then convert to target format

Integration Examples

With pdf-form-filler-skill

from doc_converter import convert_document

# First convert template to fillable form
convert_document(
    input_file="form.docx",
    output_format="pdf",
    output_file="form.pdf"
)

# Then use pdf-form-filler to fill it
from pdf_form_filler import fill_pdf_form
fill_pdf_form("form.pdf", data, "filled.pdf")

With newsletter-skill

from doc_converter import convert_document

# Convert blog post to newsletter format
convert_document(
    input_file="blog_post.md",
    output_format="html",
    output_file="newsletter.html",
    options={"email_safe": True}
)

With in-depth-research-skill

from doc_converter import convert_document

# Export research as multiple formats
convert_document(
    input_file="research.md",
    output_formats=["pdf", "docx", "html"],  # Batch convert
    options={"include_toc": True, "number_sections": True}
)

With data-analysis-skill

from doc_converter import convert_document

# Export analysis results in multiple formats
convert_document(
    input_file="analysis_results.csv",
    output_formats=["json", "xml", "xlsx"],
    batch=True
)

Configuration

doc_converter:
  primary_engine: pandoc          # pandoc, python-docx, etc
  fallback_engines:
    - python-docx
    - weasyprint
    - reportlab

  format_options:
    pdf:
      engine: "wkhtmltopdf"       # or "weasyprint"
      margin: "1cm"
      font_size: "12pt"

    html:
      include_styles: true
      email_safe: false

    docx:
      preserve_images: true
      preserve_formatting: true

  batch:
    max_concurrent: 3
    progress_bar: true

Performance

Conversion	Time	Quality
MD → HTML	<500ms	Excellent
MD → PDF	1-2s	Excellent
DOCX → PDF	1-3s	Excellent
CSV → JSON	<200ms	Excellent
HTML → PDF	2-5s	Good
PDF → MD	3-10s	Fair

Error Handling

from doc_converter import (
    ConversionError, UnsupportedFormatError, FileError
)

try:
    result = convert_document("input.xyz", "pdf")
except UnsupportedFormatError:
    print("Format not supported")
except ConversionError as e:
    print(f"Conversion failed: {e}")
except FileError:
    print("File not found or not readable")

Limitations

• Some PDF → other format conversions lose quality (requires OCR)
• HTML with complex JavaScript may not render correctly
• Some DOCX formatting options don't convert to other formats
• Very large files (100+ MB) may cause memory issues
• Embedded objects may not convert perfectly

See Also

• references/format-matrix.md — Detailed conversion paths and quality notes
• references/pandoc.md — Pandoc options and template usage
• scripts/convert.sh — Universal converter wrapper script
• README.md — Full documentation