| name | utility-md-to-docx |
| description | Markdown 文書から Word（.docx）を生成する。macOS Pages で開いても表の分断・巨大空白・見出しの孤立が起きない検証済みパターン（python-docx）と、Pages 自動書き出しによるレンダリング検証ループを提供。「mdをdocxにして」「Wordファイルを作って」「docxで納品したい」「チェックリストをWordにして」などのリクエストで起動。 |
| argument-hint | [入力.md] [出力.docx] |
/utility-md-to-docx
Markdown を元に、レンダリング検証まで込みで Word（.docx）を作る。
単純な変換ツール（pandoc 等）を使わない理由: 生成した docx を macOS Pages で開くと、
keepNext や pageBreakBefore プロパティが「表が見出しから分離して次ページへ飛ぶ」
「ページの大半が空白になる」誤レイアウトを引き起こす（実測で確認済み）。本スキルは
この落とし穴を回避したビルダーを書き、実レンダリングで確認してから完了とする。
前提: python-docx（venv に pip install python-docx）。レンダリング検証は macOS + Pages。
手順
1. 入力 md の構造把握
対象の Markdown を Read し、docx で表現する要素を洗い出す:
- 見出し階層（#, ##, ###）
- 表（列数・想定列幅・行数。長い表か 1 ページに収まる表か）
- 箇条書き・注記（※〜）・コードブロックの有無
- 記入欄（チェック欄・署名欄など、受領者が書き込むセル）の有無
2. ビルダースクリプトを書く
assets/docx_helpers.py を作業ディレクトリにコピーし、それを import する
Python スクリプトとして文書ごとのビルダーを書く（汎用変換器は書かない。
文書の意図に合わせた列幅・改ページはコード化するのが確実）。
from docx import Document
from docx_helpers import (
setup_a4, add_heading, add_body, add_bullet, make_table,
add_page_break, finalize,
)
doc = Document()
content_width = setup_a4(doc)
add_heading(doc, "1. 目的")
add_body(doc, "本書は……")
make_table(
doc,
headers=["No", "項目", "確認観点", "チェック"],
col_widths_cm=[1.0, 4.0, 10.0, 2.0],
rows=[["1", "…", "…", ""]],
)
finalize(doc, "出力先.docx")
禁止事項（詳細と実測根拠 → references/pages-compat.md）:
| 禁止 | 代わりに使う |
|---|
paragraph_format.keep_with_next | 使わない。見出しの孤立は手順 4 のループで調整 |
paragraph_format.page_break_before | add_page_break()（改ページ文字 w:br の独立段落） |
w:trHeight の手動 append | set_row_height()（python-docx API のみ） |
| セル幅だけ設定して列幅未設定 | make_table()（tblGrid と tcW を一致させる） |
cell.vertical_alignment 後の w:shd append | set_cell_text(bg=...)（正しい要素順で処理） |
3. ビルドとスキーマ検証
venv/bin/python builder.py
生成後、document-skills:docx プラグインの validate.py でスキーマ検証する
（パスは ~/.claude/plugins/cache/**/skills/docx/scripts/office/validate.py を find で解決。
defusedxml lxml が venv に必要）。PASSED になるまで次へ進まない。
4. レンダリング検証ループ（必須・スキップ不可）
スキーマ検証だけではページ割りの問題は検出できない。Pages で実際に書き出して確認する:
open -a Pages && sleep 3 で Pages を起動- AppleScript で docx → PDF 書き出し（スクリプトは references/pages-compat.md の「レンダリング検証の手順」節）
qpdf --show-npages でページ数を取得し、抜粋 PDF を Read で目視- 次を確認する:
- 見出しと直後の表が同じページにあるか（分離していないか）
- ページに不自然な巨大空白がないか
- 見出しがページ末尾に孤立していないか
- 複数ページにまたがる表でヘッダー行が再表示されているか
- 見出しの孤立があれば、その見出しに
page_break_before=True を付けて 1→4 を再実行
- すべて解消するまで反復（通常 1〜3 周で収束）
Pages の起動エラー（-609 / -1712）への対処も references/pages-compat.md に記載。
5. 完了報告
- 出力パス・ページ数
- レンダリング検証の結果（何周で収束したか、調整した改ページ位置）
- md と docx の二重管理になる場合はその旨（どちらが編集元かを明示）
原因不明のレイアウト問題に遭遇したら
推測で直さない。疑わしい要素を 1 つずつ無効化したバリアント docx を作り、
それぞれ Pages で書き出してページ数の変化で犯人を機械判定する
（references/pages-compat.md の「二分探索」節）。
境界（対象外）
- 汎用の md→docx 一括変換（pandoc 相当）は提供しない。文書ごとにビルダーを書く
- md→PDF は対象外（Chrome headless + print.css の別パイプラインを使う）
- Windows/Word 環境でのレンダリング検証は対象外（Pages でのみ検証。Word は
keepNext 等を正しく解釈するため、Pages で正常なら Word でも概ね安全）
