mirror of
https://github.com/github/awesome-copilot.git
synced 2026-07-17 03:13:25 +00:00
github-actions[bot]
72 lines
2.6 KiB
Markdown
72 lines
2.6 KiB
Markdown
# 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+)
|
|
|
|
```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 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:
|
|
|
|
```powershell
|
|
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
|
|
|
|
```powershell
|
|
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.
|