mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-16 19:03:26 +00:00
Willie Yao
e4a1f57fd9
* feat: add convert-excel-to-md, convert-pdf-to-md, and convert-word-to-md skills Add three new agent skills that convert common document formats to Markdown using bundled Python scripts powered by MarkItDown: - convert-excel-to-md: Converts .xlsx workbooks to Markdown with per-sheet tables and embedded image extraction via a bundled Python script. - convert-pdf-to-md: Converts .pdf documents to Markdown with text/table extraction and embedded image extraction via PyMuPDF. - convert-word-to-md: Converts .docx documents to Markdown with proper image extraction replacing MarkItDown's base64 placeholders. Each skill includes: - SKILL.md with detailed usage instructions, output structure docs, and a troubleshooting table - scripts/ with the conversion Python script and requirements.txt - references/setup.md with environment setup instructions Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: remove Markdown image syntax from convert-word-to-md SKILL.md The CI valid-refs linter flagged the literal Markdown image syntax containing a data URI as an invalid file reference. Replaced it with a plain text description of the placeholder format. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * fix: update pip install command to use scripts/requirements.txt for setup * fix: clarify installation instructions for requirements-file in setup documentation * fix: correct indentation in image extraction function * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * feat: add comprehensive documentation and setup instructions for convert-to-md skills * fix: add trailing slashes to skill paths in plugin.json * fix: reorder skills in plugin.json for consistency * fix: update plugin.json and README.md for clarity and consistency * feat: add convert-to-md plugin and update related documentation * Potential fix for pull request finding Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> * fix: enhance conversion skills to handle mixed file types and improve error handling --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
74 lines
2.7 KiB
Markdown
74 lines
2.7 KiB
Markdown
# Environment Setup for convert-excel-to-md
|
|
|
|
Follow these steps exactly, in order, before running `scripts/convert_excel_to_md.py`
|
|
for the first time in a given environment. Don't skip steps or improvise
|
|
alternatives — they're written to be deterministic and safe to re-run.
|
|
|
|
## 1. Check Python is available (3.10+)
|
|
|
|
```powershell
|
|
python --version
|
|
```
|
|
|
|
- If this fails (command not found), install Python 3.10 or newer:
|
|
- Windows: `winget install --id Python.Python.3.12 -e`
|
|
- macOS: `brew install python@3.12`
|
|
- Linux (Debian/Ubuntu): `sudo apt-get update && sudo apt-get install -y python3 python3-pip python-is-python3`
|
|
- If the reported version is older than 3.10, install a newer Python using
|
|
the same command above (MarkItDown requires 3.10+).
|
|
|
|
## 2. Check pip is available
|
|
|
|
```powershell
|
|
python -m pip --version
|
|
```
|
|
|
|
- If this fails, bootstrap pip:
|
|
|
|
```powershell
|
|
python -m ensurepip --upgrade
|
|
```
|
|
|
|
## 3. Install MarkItDown with Excel (.xlsx) support
|
|
|
|
Use the `scripts/requirements.txt` file bundled with this skill to install a pinned,
|
|
known-good version of the dependency:
|
|
|
|
```powershell
|
|
python -m pip install -r scripts/requirements.txt
|
|
```
|
|
|
|
This pulls in `markitdown[xlsx]` (MarkItDown's XLSX table conversion
|
|
dependencies, which include `pandas` and `openpyxl`). No extra package is needed for image extraction — this
|
|
skill's script reads embedded images directly from the `.xlsx` zip
|
|
structure using Python's built-in `zipfile` and `xml` modules.
|
|
|
|
## 4. Verify the install
|
|
|
|
```powershell
|
|
python -c "from markitdown import MarkItDown; print('markitdown OK')"
|
|
```
|
|
|
|
Expect to see `markitdown OK` printed with no errors. If you see
|
|
`ModuleNotFoundError: No module named 'markitdown'`, repeat step 3 — pip may
|
|
be installing into a different Python environment than the one being
|
|
invoked (check `python -m pip --version` shows the same path as `python
|
|
--version`'s interpreter).
|
|
|
|
## Notes
|
|
|
|
- This setup only needs to be done once per environment/virtual environment,
|
|
not once per conversion.
|
|
- `convert_excel_to_md.py` itself also checks for `markitdown` at startup
|
|
and prints a pointer back to this file if it's missing, so re-running
|
|
setup is safe and idempotent.
|
|
- Only `.xlsx` is supported by this skill. Legacy binary `.xls` files are
|
|
out of scope (a completely different, harder-to-parse file format) — ask
|
|
the user to re-save the file as `.xlsx` (Excel: File > Save As > Excel
|
|
Workbook (.xlsx)) if one is encountered.
|
|
- Chart objects (as opposed to embedded pictures) are not extracted as
|
|
images — only raster pictures actually embedded in the workbook's
|
|
`xl/media` folder are. Native Excel charts would need to be rendered by
|
|
Excel/LibreOffice to become images, which this lightweight skill does not
|
|
attempt.
|