この文書は、README に置くには長い利用者向けの操作手順をまとめます。
README は概要と最短手順を扱い、この文書は CLI option、画像 asset、debug 出力の詳細を扱います。変換仕様は docx2md-spec.md、実装に沿った現在の挙動は docx2md-impl-spec.md を参照してください。
ブラウザ UI は分離済みの miku-docx2md-web が担当します。この repository の通常利用 path は Node.js CLI です。
Markdown を出力します。
npm run cli -- ./sample.docx --out ./sample.md
summary を標準出力へ表示します。
npm run cli -- ./sample.docx --out ./sample.md --summary
summary をファイルへ保存します。
npm run cli -- ./sample.docx --out ./sample.md --summary-out ./sample.summary.txt
解決可能な画像 asset も出力します。
npm run cli -- ./sample.docx --out ./sample.md --assets-dir ./sample.assets
unsupported 要素の debug comment も出力します。
npm run cli -- ./sample.docx --out ./sample.md --debug
進捗と処理時間の診断を stderr に出力します。
npm run cli -- ./sample.docx --out ./sample.md --verbose
バージョンを確認します。
npm run cli -- --version
CLI の詳細な契約、出力先、asset、終了コード、実行例を確認します。
npm run cli -- --help
--verbose の出力は verbose: prefix 付きで stderr に出ます。Markdown を stdout に出す場合でも、primary output とは混ざりません。
| Option | Description |
|---|---|
--out <file> |
Markdown の出力先 |
--assets-dir <dir> |
解決可能な埋め込み画像 asset の出力先 |
--summary |
summary を標準出力へ表示 |
--summary-out <file> |
summary の出力先 |
--debug |
unsupported 要素の HTML comment trace を Markdown に含める |
--include-unsupported-comments |
--debug と同じ |
--verbose |
進捗と処理時間の診断を verbose: prefix 付きで stderr に出力 |
--version |
バージョンを表示 |
--help |
ヘルプを表示 |
--assets-dir <dir> を指定すると、解決可能な埋め込み画像が asset directory 配下へ保存されます。
出力 path の例:
manifest.jsonword/media/example.png可能な場合、Markdown 内の画像 placeholder は相対画像 link に変換されます。
asset 出力なし:
[Image: Example alt text]
asset 出力あり:
asset 出力には manifest.json が含まれます。
manifest には次の情報が入ります。
[Content_Types].xml がある場合、拡張子による推定より package-declared content type を優先します。
通常、unsupported 要素は Markdown に出力されません。
--debug または --include-unsupported-comments を使うと、簡潔な HTML comment が出力されます。
例:
<!-- unsupported: drawing -->
debug comment は診断用です。最終的な文章として読ませる用途ではありません。
実際の .docx ファイルで変換品質を確認する場合は、quality-check.md の手順を使います。