mirror of https://github.com/github/awesome-copilot.git synced 2026-07-16 19:03:26 +00:00

Files

T

Willie Yao e4a1f57fd9 feat: add convert-excel-to-md, convert-pdf-to-md, and convert-word-to-md skills (#2294 )

* 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>

2026-07-16 09:06:49 +10:00

2.6 KiB

Raw Blame History

Environment Setup for convert-pdf-to-md

Follow these steps exactly, in order, before running scripts/convert_pdf_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+)

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

python -m pip --version

If this fails, bootstrap pip:

python -m ensurepip --upgrade

3. Install MarkItDown with PDF support, plus PyMuPDF for image extraction

Use the scripts/requirements.txt file bundled with this skill to install pinned, known-good versions of the dependencies:

python -m pip install -r scripts/requirements.txt

This pulls in markitdown[pdf] and pymupdf>=1.24.0. PyMuPDF (imported as fitz) is required separately because MarkItDown's PDF converter only extracts text and tables — it has no support for embedded images at all, so this skill's script extracts them itself.

4. Verify the install

python -c "from markitdown import MarkItDown; import fitz; print('markitdown + pymupdf OK')"

Expect to see markitdown + pymupdf OK printed with no errors. If you see a ModuleNotFoundError, 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_pdf_to_md.py itself also checks for markitdown and fitz at startup and prints a pointer back to this file if either is missing, so re-running setup is safe and idempotent.
Only .pdf is supported by this skill — it's MarkItDown's only PDF-family format, so there's no legacy-format equivalent to worry about (unlike Word's .doc or Excel's .xls).
Scanned/image-only PDFs (no embedded text layer) will produce little or no text from MarkItDown, since it does not perform OCR. The images themselves will still be extracted and appended, but the text body may be empty or near-empty in that case — mention this to the user if it happens.

2.6 KiB Raw Blame History