awesome-copilot/skills/convert-word-to-md/references/setup.md

Environment Setup for convert-word-to-md

Follow these steps exactly, in order, before running scripts/convert_word_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 Word (.docx) support

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

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

This pulls in markitdown[docx] (MarkItDown's Word conversion dependency, which includes mammoth for .docx file parsing). No extra package is needed — this skill's script uses MarkItDown's built-in Word converter.

4. Verify the install

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_word_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 .docx is supported by this skill. Legacy binary .doc files are out of scope — ask the user to re-save the file as .docx (e.g., via Word's "Save As") if one is encountered.