設定ガイド

YAML設定ファイルを通じてドキュメントのスタイリングをカスタマイズする方法を学びます。

設定ファイルの構造

md2docxは、ドキュメントのスタイリングを定義するためにYAMLファイルを使用します。すべての設定はスキーマバージョン2.0に従います。

設定キー

トップレベルの設定キー（必須）：

SchemaVersion: スキーマバージョン識別子 Metadata: プリセットのメタデータと情報 TextDirection: テキストの流れ方向（HorizontalまたはVertical） PageLayout: ページサイズとマージン設定 Fonts: フォントファミリーとサイズ設定 Styles: 要素ごとのスタイリングルール

基本構造

SchemaVersion: "2.0"

Metadata:
  Name: "カスタムスタイル"
  Description: "私のドキュメント用のカスタムスタイリング"
  Author: "あなたの名前"
  Version: "1.0.0"

TextDirection: "Horizontal"  # または縦書きの場合は "Vertical"

PageLayout:
  Width: 21.0      # A4幅（cm）
  Height: 29.7     # A4高さ（cm）
  # ... 余白設定

Fonts:
  Ascii: "Noto Serif"
  EastAsia: "Noto Serif CJK JP"
  DefaultSize: 11

Styles:
  H1:
    Size: 26
    Bold: true
    Color: "2c3e50"
    # ... 追加のプロパティ
  # ... その他の要素のスタイル

設定セクション

メタデータ

プリセットに関する説明情報：

Metadata:
  Name: "マイスタイル"           # 表示名
  Description: "このスタイルの簡単な説明"
  Author: "あなたの名前"         # 作成者名
  Version: "1.0.0"              # セマンティックバージョン

テキスト方向

ドキュメント内のテキストの流れを制御：

TextDirection: "Horizontal"  # 左から右、上から下
# または
TextDirection: "Vertical"    # 上から下、右から左（日本語縦書き）

重要：縦書きテキストは日本語ドキュメントと小説用に最適化されています。

ページレイアウト

ページの寸法と余白を定義（すべての値はセンチメートル）：

PageLayout:
  Width: 21.0              # ページ幅
  Height: 29.7             # ページ高さ
  MarginTop: 2.54          # 上余白
  MarginBottom: 2.54       # 下余白
  MarginLeft: 3.17         # 左余白
  MarginRight: 3.17        # 右余白
  MarginHeader: 1.27       # ヘッダー余白（端からの距離）
  MarginFooter: 1.27       # フッター余白（端からの距離）
  MarginGutter: 0          # のど（製本用）

一般的なページサイズ：

A4: 21.0 × 29.7 cm
レター: 21.59 × 27.94 cm
A5: 14.8 × 21.0 cm（縦書き小説で一般的）

フォント

フォントファミリーとデフォルトサイズを指定：

Fonts:
  Ascii: "Noto Serif"              # ASCII文字用フォント
  EastAsia: "Noto Serif CJK JP"    # 日本語/中国語/韓国語用フォント
  DefaultSize: 11                   # デフォルトフォントサイズ（ポイント）

利用可能なフォント（Dockerイメージ内）：

セリフ: Noto Serif、Noto Serif CJK JP
サンセリフ: Noto Sans、Noto Sans CJK JP
等幅: Noto Sans Mono、Noto Sans Mono CJK JP

注意：.NET CLIを使用する場合は、システムにフォントがインストールされていることを確認するか、一貫したフォント処理のためにDockerを使用してください。

タイトルページ

表紙/タイトルページに中央配置の画像を設定:

TitlePage:
  Enabled: false                    # タイトルページを有効化
  ImagePath: "cover.jpg"           # 画像パス（入力ファイルからの相対パスまたは絶対パス）
  ImageMaxWidthPercent: 80          # 印刷可能領域に対する最大幅（%）
  ImageMaxHeightPercent: 80         # 印刷可能領域に対する最大高さ（%）
  PageBreakAfter: true              # タイトルページ後の改ページ

CLIオーバーライド: --cover-image <file> でコマンドラインからカバー画像を指定できます。これによりタイトルページが暗黙的に有効化され、YAMLの ImagePath がオーバーライドされます。

対応フォーマット: PNG、JPEG

スタイル

各Markdown要素のスタイリングを定義します。

見出しスタイル（H1-H6）

Styles:
  H1:
    Size: 26                    # フォントサイズ（ポイント）
    Bold: true                  # 太字
    Italic: false               # 斜体（オプション）
    Color: "2c3e50"            # 16進数カラー（#なし）
    ShowBorder: true            # 枠線を表示
    BorderColor: "3498db"       # 枠線の色（16進数）
    BorderSize: 6               # 枠線の太さ（1/8ポイント）
    BorderPosition: "bottom"    # "top"、"bottom"、"left"、"right"
    SpaceBefore: "600"          # 前の間隔（twips、1/20ポイント）
    SpaceAfter: "300"           # 後の間隔（twips）

間隔の値（twips = 1/20ポイント）：

"240" = 12pt間隔
"360" = 18pt間隔
"480" = 24pt間隔
"600" = 30pt間隔

段落スタイル

Styles:
  Paragraph:
    Size: 11                    # フォントサイズ
    Color: "2c3e50"            # テキストカラー
    LineSpacing: "360"          # 行間（twips：240=1.0、360=1.5、480=2.0）
    FirstLineIndent: "0"        # 1行目のインデント（twips）
    LeftIndent: "0"             # 左インデント（twips）
    InlineCodeFontAscii: "Courier New"          # インラインコードのASCIIフォント
    InlineCodeFontEastAsia: "Noto Sans Mono CJK JP"  # インラインコードの東アジアフォント

行間の例：

"240" = シングルスペース（1.0）
"360" = 1.5スペース
"480" = ダブルスペース（2.0）

インデントの例：

"0" = インデントなし
"360" = 0.5cmインデント
"720" = 1cmインデント

リストスタイル

Styles:
  List:
    Size: 11                    # フォントサイズ
    Color: "2c3e50"            # テキストカラー
    LeftIndent: "720"           # 左余白（twips）
    HangingIndent: "360"        # 箇条書き/番号のぶら下げインデント
    SpaceBefore: "60"           # 各項目の前の間隔
    SpaceAfter: "60"            # 各項目の後の間隔

コードブロックスタイル

Styles:
  CodeBlock:
    Size: 10                              # フォントサイズ
    Color: "2c3e50"                      # テキストカラー
    BackgroundColor: "ecf0f1"            # 背景色
    BorderColor: "bdc3c7"                # 枠線の色
    MonospaceFontAscii: "Noto Sans Mono"           # 等幅フォント（ASCII）
    MonospaceFontEastAsia: "Noto Sans Mono CJK JP" # 等幅フォント（CJK）
    LineSpacing: "280"                   # 行間
    SpaceBefore: "300"                   # 前の間隔
    SpaceAfter: "300"                    # 後の間隔
    ShowBorder: true                     # 枠線を表示
    BorderSize: 4                        # 枠線の太さ
    BorderSpace: 4                       # 枠線とテキスト間の余白（ポイント）

画像スタイル

Styles:
  Image:
    MaxWidthPercent: 100        # 印刷可能領域に対する最大幅（%、1-100）
    Alignment: "center"         # "left"、"center"、"right"

注意：

対応フォーマット：PNGおよびJPEG
MaxWidthPercent：画像は印刷可能幅のこの割合に収まるよう比例縮小されます。デフォルトは 100。
Alignment：画像を含む段落の配置を制御します。デフォルトは "center"。
Markdownで指定した画像パスは、入力 .md ファイルのディレクトリからの相対パスで解決されます。

引用ブロックスタイル

Styles:
  Quote:
    Size: 11                    # フォントサイズ
    Color: "7f8c8d"            # テキストカラー
    Italic: true                # 斜体
    ShowBorder: true            # 左枠線を表示
    BorderColor: "3498db"       # 枠線の色
    BorderSize: 16              # 枠線の太さ（1/8ポイント単位：16=2pt、24=3pt）
    BorderSpace: 0              # 枠線とテキストの間隔（ポイント）
    BorderPosition: "left"      # 枠線の位置（left/right/top/bottom）
    BackgroundColor: "f8f9fa"   # 背景色（省略可）
    LeftIndent: "720"           # 左インデント（twips）
    SpaceBefore: "300"          # 前の間隔（twips）
    SpaceAfter: "300"           # 後の間隔（twips）
    PaddingSpace: 0             # BackgroundColor設定時の内側パディング（ポイント）
    InlineCodeFontAscii: "Courier New"          # インラインコードのASCIIフォント
    InlineCodeFontEastAsia: "Noto Sans Mono CJK JP"  # インラインコードの東アジアフォント

カスタムプリセットの作成

ステップ1：既存のプリセットをコピー

cp config/presets/default.yaml config/custom/my-style.yaml

ステップ2：設定を編集

希望のスタイリングでYAMLファイルを変更：

SchemaVersion: "2.0"

Metadata:
  Name: "企業スタイル"
  Description: "ビジネス文書用のプロフェッショナルスタイリング"
  Author: "あなたの会社"
  Version: "1.0.0"

TextDirection: "Horizontal"

PageLayout:
  Width: 21.0
  Height: 29.7
  # ... 余白をカスタマイズ

Fonts:
  Ascii: "Noto Sans"
  EastAsia: "Noto Sans CJK JP"
  DefaultSize: 10

Styles:
  H1:
    Size: 22
    Bold: true
    Color: "003366"  # コーポレートブルー
    ShowBorder: true
    BorderColor: "003366"
    # ... 追加のプロパティ

ステップ3：カスタムプリセットを使用

カスタムYAMLファイルを使用：

docker run --rm -v $(pwd):/workspace forest6511/md2docx:latest \
  input.md -o output.docx -c config/custom/my-style.yaml

プリセット名を使用（プリセットディレクトリに配置した場合）：

docker run --rm -v $(pwd):/workspace forest6511/md2docx:latest \
  input.md -o output.docx -p my-style --preset-dir /workspace/config/custom

カラーリファレンス

カラーは#プレフィックスなしの16進数値で指定します。

一般的なカラー

カラー名	16進数値	例
黒	`000000`	■
ダークグレー	`333333`	■
ミディアムグレー	`7f8c8d`	■
ライトグレー	`95a5a6`	■
ネイビーブルー	`2c3e50`	■
ダークブルー	`34495e`	■
ブルー	`3498db`	■
ライトブルー	`0066cc`	■

ベストプラクティス

1. 一貫性を維持

ドキュメント全体で同じフォントファミリーを使用
カラーパレットを限定（2-3色のメインカラー）
一貫した間隔パターン

2. 読みやすさ優先

行間：段落には少なくとも1.5倍の間隔（"360"）を使用
フォントサイズ：本文テキストは10-12pt、見出しはより大きく
コントラスト：テキストと背景の間に十分なコントラストを確保

3. プロフェッショナルな外観

過度な枠線や色を避ける
適切な余白を使用（最小2-3cm）
一貫した見出し階層

4. ターゲットプラットフォームでテスト

サンプルドキュメントを生成してWord/LibreOfficeでテスト
フォントが正しくレンダリングされることを確認
必要に応じて印刷出力でページレイアウトを確認

検証

使用前にYAML設定を検証：

# Pythonを使用
python3 -c "import yaml; yaml.safe_load(open('config/custom/my-style.yaml'))"

# Rubyを使用
ruby -e "require 'yaml'; YAML.load_file('config/custom/my-style.yaml')"

エラーが表示されなければ、YAMLは有効です。

トラブルシューティング

フォントが見つからない

問題：生成されたドキュメントが指定と異なるフォントを使用している

解決方法：

Dockerイメージを使用（フォント埋め込み済み）
システムにNotoフォントをインストール
フォント名が正確に一致することを確認（大文字小文字を区別）

枠線が表示されない

問題：枠線設定が出力に表示されない

確認事項：

ShowBorder: trueが設定されている
BorderSizeが十分である（6以上を試す）
BorderColorに有効な16進数値がある

間隔の問題

問題：間隔が正しく表示されない