md-to-docx

md-to-docx

Markdown から .docx を確実に生成するには、このスキルを使用します。

ワークフロー

1. 実行モードを決定します。
   • ファイル間の変換には CLI モードを使用します。
   • アプリのコードへの統合にはプログラムモードを使用します。
2. 入力元（Markdown ファイルまたは Markdown 文字列）を確認します。
3. 出力先（.docx ファイルのパスまたはブラウザーからのダウンロード）を確認します。
4. 要求された場合にのみ、オプション（配置、サイズ、方向、フォントファミリー、置換、テンプレート、セクション、ページ番号）を適用します。
5. 変換を実行し、出力先のパスまたはファイル名を報告します。

CLI モード

次のコマンドを使用します。

npx @mohtasham/md-to-docx input.md output.docx
md-to-docx input.md output.docx
md-to-docx input.md output.docx --options options.json
md-to-docx input.md output.docx -o options.json
md-to-docx --help

CLI の仕様：

• 必須の位置引数：<input.md> <output.docx>
• オプションファイル：--options <options.json> または -o <options.json>
• オプション JSON には、API と同じ形式の style、template、sections、textReplacements を含めることができます
• ヘルプフラグ：-h または --help
• 成功時は、DOCX created at: <absolute-path> が表示されます
• 参照 DOCX モードではバイナリ入力が必要です。これらはプログラム API であり、CLI フラグではありません。

プログラムモード

import { convertMarkdownToDocx, downloadDocx } from "@mohtasham/md-to-docx";

const markdown = "# Title\n\nHello **DOCX**.";
const blob = await convertMarkdownToDocx(markdown, {
  documentType: "report",
  style: {
    fontFamily: "Trebuchet MS",
    heading1Alignment: "CENTER",
    paragraphAlignment: "JUSTIFIED",
    codeBlockAlignment: "LEFT",
    direction: "LTR"
  }
});

downloadDocx(blob, "output.docx");

convertMarkdownToDocx(markdown, options?) を使用して DOCX Blob を生成します。 downloadDocx(blob, filename?) はブラウザー環境でのみ使用します。

参照 DOCX ワークフロー

次のいずれかを明示的に選択します。

• convertMarkdownWithReferenceDocxToBuffer(markdown, referenceBytes, options?) は、Markdown が本文を新規に生成し、参照ファイルの名前付きスタイル、テーマ／フォント、最終セクションのページレイアウト、ヘッダー／フッターを適用します。
• patchMarkdownInDocxToBuffer(referenceBytes, patches, options?) は既存の本文を保持し、{{body}} などの名前付きプレースホルダーを置き換えます。

参照スタイルを使用した生成では、参照ファイル内の静的な本文テキストはコピーされません。スタイル名が重複している場合は、正確な { id: "..." } セレクターを優先してください。Word 上で表示される名前を指定するには、{ name: "..." } を使用します。アップロードされた参照ファイルは信頼できないものとして扱い、呼び出し元に正当な理由がない限り、デフォルトの ZIP 制限を維持してください。

複数セクションのドキュメント

共有のデフォルトには options.template を、セクションごとの Markdown と上書き設定には options.sections を使用します。

const blob = await convertMarkdownToDocx("", {
  template: {
    footers: {
      default: { pageNumberDisplay: "currentAndTotal", alignment: "CENTER" }
    }
  },
  sections: [
    {
      markdown: "# Cover Page\n\nIntroduction here.",
      titlePage: true,
      headers: { first: { text: "Confidential", alignment: "RIGHT" } },
      pageNumbering: { start: 1, display: "none" }
    },
    {
      markdown: "# Chapter 1\n\nBody content.",
      style: { paragraphAlignment: "JUSTIFIED" },
      pageNumbering: { start: 1, display: "currentAndTotal" }
    }
  ]
});

各セクションでは、style、headers、footers、pageNumbering、page（余白／サイズ／向き）、titlePage、type（改ページの種類）を上書きできます。

マージの優先順位：

• グローバルな style が最初に適用されます
• template がセクション共通のデフォルトを設定します
• セクションごとのオプションが最後に優先されます

一般的なフッターのページ番号モードには、pageNumbering.display を使用します：none、current、currentAndTotal、currentAndSectionTotal。

図と表の参照

独立した画像または表の後に、Pandoc 形式のキャプション段落を配置します。ブロックとキャプションの間には空行を入れます。本文では [@fig:id] または [@tbl:id] を使用します。

See [@fig:flow] and [@tbl:metrics].

![Accessible flow diagram](flow.png)

: Request *flow* {#fig:flow}

| Metric | Value |
| --- | --- |
| p95 | 120 ms |

: Performance metrics {#tbl:metrics}

図と表の番号はセクションをまたいで継続します。ラベル、配置、整列、斜体、サイズ、failureMode の設定には options.captions を使用します。参照 DOCX のパッチモードでは、この構文は検証エラーとなります。

テキストの置換

変換前にテキストを書き換えるには、textReplacements を使用します。

const blob = await convertMarkdownToDocx("# Hello oldText", {
  textReplacements: [
    { find: /oldText/g, replace: "newText" },
    { find: "Hello", replace: "Hi" }
  ]
});

対応する Markdown 機能

対応機能：

• 見出し # から #####
• 順序付き／順序なしリスト
• 太字、斜体、下線（++text++）、取り消し線（~~text~~）
• fontFamily スタイルオプションによるカスタムフォントファミリー
• 引用
• 表（セル内のインライン書式：太字、斜体、コード、リンク、取り消し線）
• コードブロックとインラインコード（codeBlockAlignment で配置を設定可能）
• リンクと画像
• 図／表キャプションの自動採番と、クリック可能な相互参照
• textReplacements によるレンダリング前のテキスト置換
• COMMENT: ...
• 単独行の [TOC]
• 単独行の \pagebreak
• Markdown のテーマ区切り（---、***、___）は、Word の段落罫線としてレンダリングされます

スタイルオプションのクイックリファレンス

オプション	値	デフォルト
paragraphAlignment	LEFT、CENTER、RIGHT、JUSTIFIED	LEFT
headingAlignment	同上	LEFT
heading1Alignment–heading5Alignment	同上	LEFT
blockquoteAlignment	同上	LEFT
codeBlockAlignment	同上	LEFT
fontFamily	任意のフォント名文字列	Calibri
direction	LTR、RTL	LTR
tableLayout	autofit、fixed	autofit
tocFontSize	数値	ライブラリのデフォルト

トラブルシューティング

• CLI で引数エラーが発生する場合は、位置引数としてパスが正確に 2 つ指定されていることを再確認してください。
• オプションの解析に失敗する場合は、JSON 構文を検証し、ルートがオブジェクトであることを確認してください。
• 出力が見つからない場合は、出力先ディレクトリの権限とパスの表記を確認してください。
• Node でファイルが必要な場合は、downloadDocx を使わずに、返された Blob のバイトデータをディスクに書き込んでください。
• セクションで予期しない番号付けが行われる場合は、各セクションで pageNumbering.start を設定して番号をリセットしてください。
• 先頭ページのヘッダーやフッターが表示されない場合は、そのセクションで titlePage: true を設定してください。