Docx To Markdown

1. Identify the Source File

Confirm the .docx file path with the user. If not provided, ask for it.

2. Determine Output Location

• Default: same directory as the source, with .md extension
• If the user specifies a target path, use that instead
• Create an images/ subdirectory next to the output file for extracted media

3. Run the Conversion

Execute the conversion script:

bash .github/skills/docx-to-markdown/scripts/convert.sh "<input.docx>" "<output.md>"

The script:

• Converts the document using pandoc with GitHub-Flavored Markdown (gfm)
• Extracts embedded images to an images/ folder next to the output
• Updates image references to use relative paths

4. Post-Processing Cleanup

After conversion, review and fix the output:

1. Heading hierarchy — Ensure a single # top-level heading; adjust if pandoc produced multiple H1s
2. Tables — Verify table formatting renders correctly in GFM
3. Images — Confirm all extracted images exist in the images/ directory and paths resolve
4. Links — Check for broken or absolute links that need updating
5. Artifacts — Remove Word-specific artifacts (e.g., \newpage, empty anchors, {.underline} attributes)
6. Lists — Ensure nested lists use consistent indentation (2 or 4 spaces)
7. Whitespace — Remove excessive blank lines (collapse 3+ consecutive blank lines to 2)

5. Validate

• Open the generated .md file and confirm it renders correctly
• Verify image references resolve to actual files
• Report the output file path and any issues found to the user