147 lines
4.1 KiB
Markdown
147 lines
4.1 KiB
Markdown
---
|
|
name: markdown-tools
|
|
description: Converts documents to markdown (PDFs, Word docs, PowerPoint, Confluence exports) with Windows/WSL path handling. Activates when converting .doc/.docx/PDF/PPTX files to markdown, processing Confluence exports, handling Windows/WSL path conversions, or working with markitdown utility.
|
|
---
|
|
|
|
# Markdown Tools
|
|
|
|
## Overview
|
|
|
|
This skill provides document conversion to markdown with Windows/WSL path handling support. It helps convert various document formats to markdown and handles path conversions between Windows and WSL environments.
|
|
|
|
## Core Capabilities
|
|
|
|
### 1. Markdown Conversion
|
|
Convert documents to markdown format with automatic Windows/WSL path handling.
|
|
|
|
### 2. Confluence Export Processing
|
|
Handle Confluence .doc exports with special characters for knowledge base integration.
|
|
|
|
## Quick Start
|
|
|
|
### Convert Any Document to Markdown
|
|
|
|
```bash
|
|
# Basic conversion
|
|
markitdown "path/to/document.pdf" > output.md
|
|
|
|
# WSL path example
|
|
markitdown "/mnt/c/Users/username/Documents/file.docx" > output.md
|
|
```
|
|
|
|
See `references/conversion-examples.md` for detailed examples of various conversion scenarios.
|
|
|
|
### Convert Confluence Export
|
|
|
|
```bash
|
|
# Direct conversion for simple exports
|
|
markitdown "confluence-export.doc" > output.md
|
|
|
|
# For exports with special characters, see references/
|
|
```
|
|
|
|
## Path Conversion
|
|
|
|
### Windows to WSL Path Format
|
|
|
|
Windows paths must be converted to WSL format before use in bash commands.
|
|
|
|
**Conversion rules:**
|
|
- Replace `C:\` with `/mnt/c/`
|
|
- Replace `\` with `/`
|
|
- Preserve spaces and special characters
|
|
- Use quotes for paths with spaces
|
|
|
|
**Example conversions:**
|
|
```bash
|
|
# Windows path
|
|
C:\Users\username\Documents\file.doc
|
|
|
|
# WSL path
|
|
/mnt/c/Users/username/Documents/file.doc
|
|
```
|
|
|
|
**Helper script:** Use `scripts/convert_path.py` to automate conversion:
|
|
|
|
```bash
|
|
python scripts/convert_path.py "C:\Users\username\Downloads\document.doc"
|
|
```
|
|
|
|
See `references/conversion-examples.md` for detailed path conversion examples.
|
|
|
|
## Document Conversion Workflows
|
|
|
|
### Workflow 1: Simple Markdown Conversion
|
|
|
|
For straightforward document conversions (PDF, .docx without special characters):
|
|
|
|
1. Convert Windows path to WSL format (if needed)
|
|
2. Run markitdown
|
|
3. Redirect output to .md file
|
|
|
|
See `references/conversion-examples.md` for detailed examples.
|
|
|
|
### Workflow 2: Confluence Export with Special Characters
|
|
|
|
For Confluence .doc exports that contain special characters or complex formatting:
|
|
|
|
1. Save .doc file to accessible location
|
|
2. Use appropriate conversion method (see references)
|
|
3. Verify output formatting
|
|
|
|
See `references/conversion-examples.md` for step-by-step command examples.
|
|
|
|
## Error Handling
|
|
|
|
### Common Issues and Solutions
|
|
|
|
**markitdown not found:**
|
|
```bash
|
|
# Install markitdown via pip
|
|
pip install markitdown
|
|
|
|
# Or via uv tools
|
|
uv tool install markitdown
|
|
```
|
|
|
|
**Path not found:**
|
|
```bash
|
|
# Verify path exists
|
|
ls -la "/mnt/c/Users/username/Documents/file.doc"
|
|
|
|
# Use convert_path.py helper
|
|
python scripts/convert_path.py "C:\Users\username\Documents\file.doc"
|
|
```
|
|
|
|
**Encoding issues:**
|
|
- Ensure files are UTF-8 encoded
|
|
- Check for special characters in filenames
|
|
- Use quotes around paths with spaces
|
|
|
|
## Resources
|
|
|
|
### references/conversion-examples.md
|
|
Comprehensive examples for all conversion scenarios including:
|
|
- Simple document conversions (PDF, Word, PowerPoint)
|
|
- Confluence export handling
|
|
- Path conversion examples for Windows/WSL
|
|
- Batch conversion operations
|
|
- Error recovery and troubleshooting examples
|
|
|
|
Load this reference when users need specific command examples or encounter conversion issues.
|
|
|
|
### scripts/convert_path.py
|
|
Python script to automate Windows to WSL path conversion. Handles:
|
|
- Drive letter conversion (C:\ → /mnt/c/)
|
|
- Backslash to forward slash
|
|
- Special characters and spaces
|
|
|
|
## Best Practices
|
|
|
|
1. **Convert Windows paths to WSL format** before bash operations
|
|
2. **Verify paths exist** before operations using ls or test commands
|
|
3. **Check output quality** after conversion
|
|
4. **Use markitdown directly** for simple conversions
|
|
5. **Test incrementally** - Verify each conversion step before proceeding
|
|
6. **Preserve directory structure** when doing batch conversions
|