Skip to content

DOCX_CONVERSION.md

Latest commit

 

History

History
180 lines (123 loc) · 4.97 KB

DOCX_CONVERSION.md

File metadata and controls

180 lines (123 loc) · 4.97 KB
Raw

Markdown → DOCX Conversion

This repository includes scripts to convert all Markdown (*.md) files to Microsoft Word (.docx) format using Pandoc.

Why Pandoc (and not markitdown)?

microsoft/markitdown is a tool that converts other formats → Markdown (PDF, Word, Excel, PowerPoint, HTML, …). It works in the opposite direction from what is needed here.
markitdown has no Markdown → DOCX output capability, so it is not suitable for this task.

Pandoc is the industry-standard converter that handles Markdown → DOCX with excellent fidelity: headings, tables, lists, footnotes, code blocks, images, and YAML front-matter metadata are all preserved. It also accepts a custom reference.docx file so the output matches any Word style guide.

Requirements

Tool Install
Pandoc ≥ 2.x pandoc.org/installing.html — available via apt, brew, winget, or the official installer
Python ≥ 3.8 Only required for the Python script; standard library only, no extra packages

Verify the installation:

pandoc --version

Scripts

Script Language Notes
scripts/convert_md_to_docx.sh Bash Linux / macOS
scripts/convert_md_to_docx.py Python 3 Cross-platform (Linux, macOS, Windows)

Both scripts produce identical output and accept the same options.

Quick start

Bash (Linux / macOS)

# Make the script executable (first time only)
chmod +x scripts/convert_md_to_docx.sh

# Convert all .md files → docx_output/
./scripts/convert_md_to_docx.sh

Python (cross-platform)

python3 scripts/convert_md_to_docx.py

Options

Flag Description Default
-o <dir> / --output-dir Directory where .docx files are written docx_output
-r <file> / --reference-doc Pandoc reference .docx for custom Word styles (none)
-t / --toc Add a table of contents to every document off
-h / --help Show help —

Examples

# Default: output to ./docx_output/
./scripts/convert_md_to_docx.sh

# Custom output directory
./scripts/convert_md_to_docx.sh -o /tmp/my_docs

# With table of contents
./scripts/convert_md_to_docx.sh -t

# With a reference .docx for custom Word styles
./scripts/convert_md_to_docx.sh -r reference.docx

# Combine options
./scripts/convert_md_to_docx.sh -o /tmp/my_docs -r reference.docx -t

# Python equivalent
python3 scripts/convert_md_to_docx.py -o /tmp/my_docs -r reference.docx --toc

Output structure

The original folder hierarchy is mirrored inside the output directory:

docx_output/
├── README.docx
├── foundry_guide.docx
├── post-mortem-doc1.docx
└── docs/
    └── foundry/
        ├── README.docx
        ├── 01-palantir-foundry-componentes.docx
        ├── 02-glosario-foundry.docx
        └── …

Custom Word styles (reference.docx)

For professional-looking output, create a reference.docx with the Word styles you want (Heading 1-3, Normal, Code, Block Quote, etc.) and pass it with -r:

# Generate a default reference template to customise
pandoc --print-default-data-file reference.docx > reference.docx

# Then open reference.docx in Word, edit styles, save, and use it:
./scripts/convert_md_to_docx.sh -r reference.docx

Excluding the output directory

docx_output/ is already listed in .gitignore so generated .docx files are not committed to the repository.

GitHub Actions workflow

The repository ships a workflow that automatically converts all Markdown files to DOCX and uploads them as a downloadable artifact — no local Pandoc installation required.

File: .github/workflows/convert-md-to-docx.yml

Triggers

Trigger When
Manual (workflow_dispatch) Launch from the Actions tab at any time
Automatic (push) Runs whenever a *.md file, a conversion script (convert_md_to_docx.py or convert_md_to_docx.sh), or the workflow file itself is pushed

How to download the generated files

  1. Go to Actions → Convert Markdown to DOCX in the GitHub UI.
  2. Click on any completed run.
  3. Scroll down to Artifacts and download docx-files.
  4. Unzip the archive — the DOCX files mirror the original folder structure.

Artifacts are kept for 30 days by default.

Manual run with table of contents

  1. Go to Actions → Convert Markdown to DOCX.
  2. Click Run workflow.
  3. Check "Add table of contents to every document" if desired.
  4. Click Run workflow.

Why artifacts instead of committing to the repo?

  • Keeps the repository free of generated binaries.
  • DOCX files are always regenerated from the latest Markdown source.
  • Anyone can download a fresh copy without needing Pandoc installed locally.