📄 doc-to-markdown
Universal document-to-Markdown converter. Turn PDF, Word, PowerPoint, Excel,
HTML, and text files into clean Markdown — preserving headings, tables, lists,
and structure. Designed for AI agents that need to read document content.
Supported formats
| Format |
Extensions |
Library |
Notes |
| PDF |
.pdf |
pdfplumber |
Text + tables extracted page by page |
| Word |
.docx |
python-docx |
Headings, paragraphs, tables, lists |
| PowerPoint |
.pptx |
python-pptx |
Slide-by-slide, titles + body text + tables |
| Excel |
.xlsx |
openpyxl |
Each sheet → Markdown table |
| CSV |
.csv |
stdlib csv |
First row = header row |
| HTML |
.html, .htm |
BeautifulSoup |
Strips tags, keeps structure |
| Text |
.txt, .md, .rst |
stdlib |
Pass-through with light cleanup |
How to call
python3 skills/doc-to-markdown/convert.py <input_file> [--output <output_file>] [--format json]
--output: write Markdown to a file instead of stdout--format json: return {"success": true, "markdown": "...", "format": "...", "pages": N, "tables": N} as JSON
Example — convert a PDF
python3 skills/doc-to-markdown/convert.py report.pdf --output report.md
Example — convert and get JSON
python3 skills/doc-to-markdown/convert.py slides.pptx --format json
Example — convert Word doc inline
MD=$(python3 skills/doc-to-markdown/convert.py document.docx)
echo "$MD"
Output structure
The converter produces clean Markdown with:
- PDF: Each page separated by
---, tables rendered as Markdown tables
- Word: Headings mapped to
#/##/###, tables as Markdown tables, lists preserved
- PowerPoint: Each slide as
## Slide N: <title>, body text as bullet points
- Excel: Each sheet as
## Sheet: <name>, data as Markdown table
- HTML: Semantic tags converted (h1-h6, ul/ol, table, p, code, blockquote)
Dependencies
All dependencies are pre-installed in the Starchild environment:
pdfplumber — PDF text and table extractionpython-docx — Word document parsingpython-pptx — PowerPoint parsingopenpyxl — Excel spreadsheet readingbeautifulsoup4 — HTML parsing
No API keys required. All conversion runs locally.
Error handling
- Unsupported file extension → returns error with supported formats list
- Corrupted/unreadable file → returns error with details
- Empty file → returns empty Markdown with success=true
Use cases
- Feed document content to an LLM for summarization or Q&A
- Extract structured data from reports for analysis
- Convert legacy documents for migration
- Make attachments readable in agent workflows
- Preprocess files for RAG pipelines
1---2name: 6171-doc-to-markdown3description: Universal document-to-Markdown converter. Convert PDF, Word (.docx), PowerPoint (.pptx), Excel (.xlsx/.csv), HTML, and plain text files into clean, LLM-friendly Markdown. Extracts text, tables, images references, and structure (headings, lists, slides) with proper formatting preservation. Use when the user asks to convert a document to Markdown, extract text from a PDF/Word/PPT/Excel file, or make document content readable for AI processing.4---56# 📄 doc-to-markdown78Universal document-to-Markdown converter. Turn PDF, Word, PowerPoint, Excel,9HTML, and text files into clean Markdown — preserving headings, tables, lists,10and structure. Designed for AI agents that need to read document content.1112## Supported formats1314| Format | Extensions | Library | Notes |15|---|---|---|---|16| PDF | `.pdf` | `pdfplumber` | Text + tables extracted page by page |17| Word | `.docx` | `python-docx` | Headings, paragraphs, tables, lists |18| PowerPoint | `.pptx` | `python-pptx` | Slide-by-slide, titles + body text + tables |19| Excel | `.xlsx` | `openpyxl` | Each sheet → Markdown table |20| CSV | `.csv` | stdlib `csv` | First row = header row |21| HTML | `.html`, `.htm` | `BeautifulSoup` | Strips tags, keeps structure |22| Text | `.txt`, `.md`, `.rst` | stdlib | Pass-through with light cleanup |2324## How to call2526```bash27python3 skills/doc-to-markdown/convert.py <input_file> [--output <output_file>] [--format json]28```2930- `--output`: write Markdown to a file instead of stdout31- `--format json`: return `{"success": true, "markdown": "...", "format": "...", "pages": N, "tables": N}` as JSON3233### Example — convert a PDF3435```bash36python3 skills/doc-to-markdown/convert.py report.pdf --output report.md37```3839### Example — convert and get JSON4041```bash42python3 skills/doc-to-markdown/convert.py slides.pptx --format json43```4445### Example — convert Word doc inline4647```bash48MD=$(python3 skills/doc-to-markdown/convert.py document.docx)49echo "$MD"50```5152## Output structure5354The converter produces clean Markdown with:5556- **PDF**: Each page separated by `---`, tables rendered as Markdown tables57- **Word**: Headings mapped to `#`/`##`/`###`, tables as Markdown tables, lists preserved58- **PowerPoint**: Each slide as `## Slide N: <title>`, body text as bullet points59- **Excel**: Each sheet as `## Sheet: <name>`, data as Markdown table60- **HTML**: Semantic tags converted (h1-h6, ul/ol, table, p, code, blockquote)6162## Dependencies6364All dependencies are pre-installed in the Starchild environment:65- `pdfplumber` — PDF text and table extraction66- `python-docx` — Word document parsing67- `python-pptx` — PowerPoint parsing68- `openpyxl` — Excel spreadsheet reading69- `beautifulsoup4` — HTML parsing7071No API keys required. All conversion runs locally.7273## Error handling7475- Unsupported file extension → returns error with supported formats list76- Corrupted/unreadable file → returns error with details77- Empty file → returns empty Markdown with success=true7879## Use cases8081- Feed document content to an LLM for summarization or Q&A82- Extract structured data from reports for analysis83- Convert legacy documents for migration84- Make attachments readable in agent workflows85- Preprocess files for RAG pipelines
starchild-ai-agent