静的サイトジェネレータ向けドキュメントの準備：一貫性と検索可能性を実現するファイル変換戦略

Static site generators（SSG）は、モダンなドキュメントポータル、開発者ブログ、製品ナレッジベースの背骨となっています。軽量な配信、バージョン管理されたコンテンツ、CI パイプラインとのシームレスな統合を実現します。ただし、SSG は非常に特定のフォーマット（主に Markdown、reStructuredText、またはプレーン HTML）を前提としており、フロントマターのメタデータを使ってナビゲーション、テーマ付け、検索インデックスを制御します。組織が Word ファイル、PDF、PowerPoint デッキ、レガシーなヘルプ執筆フォーマットといった混在したコレクションを引き継いだ場合、変換ステップがボトルネックとなり、一貫性、アクセシビリティ、検索品質が脅かされます。

本記事では、異種ソース文書をクリーンな SSG 対応リポジトリに変換する実践的なワークフローを解説します。意味論的構造の保持、検索可能テキストの保持、重要メタデータの保持、そして PDF を計画なしに Markdown にリップしてしまう際に起こりがちな微妙な品質低下を回避することに焦点を当てます。手法は汎用的に適用可能ですが、例では convertise.app（プライバシーに配慮したクラウド変換サービス） のワークフロー機能を参照します。

なぜ変換ステップが SSG 主導のドキュメントにとって重要なのか

SSG はビルド時にソースファイルから静的 HTML サイトを生成します。ジェネレータはバイナリ形式を解釈せず、テキストを読み込みテンプレートで装飾するだけです。PDF をそのままパイプラインに流し込むと、ジェネレータはそれを不透明なアセットとして扱い、内部のコンテンツは検索エンジンにも内部検索にも見えなくなります。結果として、全文検索で情報が見つからず、構造化された HTML が提供するアクセシビリティ（例：スクリーンリーダーのナビゲーション）も失われます。

検索性以外にも、変換は次の点に影響します。

• ナビゲーション階層 – ソースの見出しがサイトの目次になります。変換時に見出しレベルが平坦化されると、利用者が期待する論理的な流れが崩れます。
• コードスニペット – 多くの技術文書はシンタックスハイライトが必要なコードブロックを含みます。PDF をリップすると等幅フォントが通常テキストに変換され、マークアップが失われます。
• 相互参照 – 図表や脚注は通常 ID で参照されます。ID が失われるとサイト全体でリンク切れが発生します。
• メタデータ – 公開日、著者、バージョン、タグはフロントマターから取得されます。変換がこれら情報を捨てると、ソート・フィルタリング・バージョン管理ができなくなります。

これらすべてに対応した厳密な変換プロセスを導入すれば、下流の再ビルドが「火消し」作業になるのを防げます。

ソースフォーマットと SSG 対応ターゲットのマッピング

まず、サポートすべきソースフォーマットをカタログ化します。以下は一般的なインベントリと推奨される SSG ターゲットです。

経験則：構造を保持できる最もシンプルなテキスト表現に変換 する – 大多数は Markdown、細かいスタイリングが必要な場合は HTML、ビジュアル中心のソースは画像セットに分離します。

変換パイプラインの準備

堅牢なパイプラインは 3 つのステージで構成されます：抽出、サニタイズ、エンリッチ。

1. 抽出 – ソースファイルからテキスト、画像、表、メタデータを取り出す。LibreOffice ヘッドレスや Microsoft Office Open XML パーサーなど、ネイティブ形式を直接読むツールが最もクリーンな出力を生成します。PDF については、テキストオブジェクトとスキャン画像を識別できるライブラリを使用してください。convertise.app はレイアウトを尊重し、抽出アセットとともにクリーンな Markdown を返す PDF‑to‑Markdown エンドポイントを提供しています。
2. サニタイズ – 生データを整形します。具体的には
   • 見出しレベルの正規化（例：ドキュメントは # から始まり、正しい階層になるように）
   • 特殊文字を UTF‑8 にエンコードし直す
   • HTML <table> を Markdown のパイプ記法に変換し、列幅揃えを保持する
   • フロントマター解析を壊す見えない空白や重複空白を除去する
3. エンリッチ – SSG 固有の情報を付加する
   • --- YAML のフロントマターに title、date、author、tags、version を記入
   • ジェネレータが対応していれば目次プレースホルダー {{ toc }} を自動生成
   • 画像最適化 – 大きなスクリーンショットは Web 向け幅（例：1200 px）にリサイズし、WebP に変換してバンドルサイズを削減

各ステージは Python、Node.js、Bash など好きな言語でスクリプト化できます。ポイントは 決定論的 に処理すること。ソースが同一であれば常に同じ出力になるようにすれば、CI ビルドの信頼性が高まります。

変換時に意味論的構造を保持する

よくある失敗は「単なるテキストダンプ」として変換してしまうことです。そうすると以下のような意味論的手がかりが失われます。

• リスト – 順序付き・順序なしリストが段落区切りだけになると階層が崩れます。
• コードブロック – インラインコードが普通のテキストに変わり、フェンスブロックから言語識別子が失われるとシンタックスハイライトが効かなくなります。
• 脚注・エンドノート – 本文に埋め込まれ、参照ナビゲーションが壊れます。

これらの落とし穴を防ぐには、変換エンジンに各構造を明示的にマッピングさせます。例として convertise.app で Word を変換する際は、preserveLists と preserveCodeBlocks オプション（API 経由で利用可能）を有効にします。結果の Markdown にはリストは - または 1. で、コードブロックは言語タグ付きのトリプルバックティックが付与されます。

以下は変換スクリプトに組み込める簡潔なマッピング表です。

• 見出し → # …（レベル1） → ## …（レベル2） → …
• 太字 → **text**
• 斜体 → *text*
• 表 → Markdown パイプ記法 | Header | …
• 画像 → ![alt text](path/to/image.ext)
• リンク → [link text](url)
• コード → language\ncode\n
• 脚注 → [^1]: footnote text

これら要素が保持されると、jekyll-toc、hugo-pagetoc などのプラグインが正確なナビゲーションを自動生成し、サイト検索インデックスも正しく解析できます。

画像・メディア資産の取り扱い

ドキュメントの大半はスクリーンショット、図、時には短い動画を含みます。変換パイプラインはこれら資産を 第一級市民 として扱うべきです。

• 抽出 – ソースから埋め込まれたすべての画像を取り出す。Word と PowerPoint では画像は別バイナリ部品として格納されているため抽出は容易。PDF の場合はラスター画像をロスレス（PNG または TIFF）でエクスポートします。
• 一貫したリネーム – docname-figure01.png など決定論的な命名規則を採用し、同名画像が別文書に出てきても衝突を防ぎます。
• 最適化 – ロスレス圧縮ツール（例：pngquant --quality=100）でサイズ削減し、続いて WebP に変換。古いブラウザ向けに PNG のフォールバックも残すと安全です。
• 参照 – 最終的な画像パスを Markdown に埋め込み、SSG が出力資産フォルダーへコピーできるようにします。

アーカイブ目的でオリジナル解像度を保持したい場合は、raw/ ディレクトリに格納し、公開サイトからは除外してリポジトリに残すだけにします。

メタデータ転送：ソースからフロントマターへ

メタデータはドキュメントのライフサイクルを紐付ける接着剤です。多くの執筆ツールは次のようなプロパティを埋め込んでいます。

• タイトル
• 著者
• 作成日・最終更新日
• バージョン番号
• キーワード／タグ

抽出時にファイルパッケージからこれらプロパティを取得します。Office Open XML の場合は core.xml 部分に Dublin Core メタデータが格納されています。PDF では XMP パケットに同様の情報が入っています。取得した情報を基に、Markdown ファイル冒頭に YAML フロントマターを生成します。

---
title: "How to Configure TLS for Apache"
author: "Jane Doe"
date: 2024-06-12
lastmod: 2025-01-03
tags: [security, apache, tls]
version: "1.3"
---

ソースに特定フィールドが無い場合は、合理的なデフォルト（例：タイトルはファイル名、date は現在日付）を使用します。リポジトリ全体でメタデータが統一されていれば、SSG はタグページ、変更ログ、RSS フィードなどを自動生成できます。

CI/CD でのワークフロー自動化

変換スクリプトが安定したら、CI パイプライン（GitHub Actions、GitLab CI、Azure Pipelines など）に組み込みます。典型的なジョブは次の通りです。

1. Checkout ドキュメントリポジトリ。
2. git diff で新規・変更されたソースファイルを検出。
3. 変更ファイルに対して、convertise.app の API を呼び出す Docker コンテナを実行し変換。
4. 生成された Markdown と資産を docs/ ブランチにコミット。
5. SSG ビルド（例：hugo --minify）をトリガー。
6. 静的サイトを CDN へデプロイ。

変換ステップが決定論的かつコンテナ内で完結するため、再現性のあるビルドが保証されます。たとえば「OCR が失敗した PDF がある」などのエラーは CI エラーとして即座に報告され、早期に対処できます。

品質保証：変換忠実度の検証

自動化は検証が伴って初めて有効です。2 層の QA を実装しましょう。

• 自動 diff – 変換後のテキストを元テキストとチェックサムまたはホワイトスペース無視の diff ツールで比較。コンテンツ削減が 5 % 超える場合は警告としてフラグ。
• ビジュアルリグレッション – 画像が多いページは、レンダリングされた HTML のスクリーンショットを取得し、pixelmatch などでベースラインと比較。テーブル崩れや CSS 欠損を捕捉します。

回帰が検出されたらデプロイを中止し、差分をプルリクエストコメントに表示させます。これにより、公開されたドキュメントが静かに劣化することを防げます。

ケーススタディ：レガシーなナレッジベースを Hugo に移行

中規模 SaaS 企業は、Word 文書、PowerPoint デッキ、アーカイブ PDF が混在したヘルプセンターを維持していました。コンテンツは共有ドライブ上にあり、サポートチームは手動でファイルを web ポータルにコピーしていました。高速かつバージョン管理がしやすい Hugo への移行を決断しました。

実施した手順

1. インベントリ作成 – スクリプトでドライブを走査し、拡張子ごとにファイルを分類。
2. バッチ変換 – convertise.app を利用し、一括ジョブで Markdown と抽出資産を content/ ディレクトリに出力。
3. メタデータマッピング – カスタム Python スクリプトで Word の core.xml プロパティを読み取り、各 Markdown にフロントマターを生成。
4. 画像パイプライン – すべてのスクリーンショットを WebP に変換し、Markdown のリンクを static/images/ フォルダーに書き換え。
5. CI 統合 – GitHub Actions が PR ごとに変換を実行し、新規サポート記事も同じプロセスを通すことを保証。

成果

• テキストが検索可能になったことで検索インデックスサイズが 40 % 減少。
• 画像を WebP 化したことでページ読み込み速度が 30 % 向上。
• サポートチームはリポジトリで直接ドキュメントを編集でき、ロールバックや監査トレイルが可能に。

この事例は、体系的な変換戦略が散在した文書ライブラリを高速・検索可能・保守性の高い静的サイトへと変えることを示しています。

SSG 対応ドキュメント変換のベストプラクティスチェックリスト

• ソースフォーマットを特定し、単一のテキストターゲット（Markdown／HTML）に統一。
• ネイティブパーサーで抽出し、テキスト・画像・メタデータを取得。
• 意味論要素（見出し、リスト、コードブロック、脚注）を保持して抽出。
• 改行コードとエンコーディングを UTF‑8 に正規化。
• 資産と Markdown のファイル名は決定論的に付与。
• title、author、date、tags、version を含むフロントマターを作成。
• 画像はロスレス圧縮＋WebP 変換し、元画像は別ディレクトリに保管。
• 変換スクリプトをコンテナ化し CI ジョブに組み込む。
• 自動 diff とビジュアルリグレッションで出力を検証。
• パイプライン手順を文書化し、貢献者が破壊的変更を加えないようにする。

結論

レガシーで異種なドキュメントを静的サイトジェネレータが扱える形式へ変換することは、単なるファイル形式の置き換えではなく、構造・メタデータ・検索性を守るdisciplined transformationです。フォーマットに依存した抽出ツールでコンテンツを取り出し、出力をサニタイズし、SSG 用フロントマターでエンリッチし、再現性のある CI パイプラインに組み込めば、ナレッジベースは常に新鮮で高速、かつ検索可能な状態を保てます。

上記のアプローチは、プライバシー優先の高品質変換サービス convertise.app を活用し、元ファイルが安全な環境から離れないまま、モダンなドキュメントワークフローに必要なクリーンな Markdown／HTML を提供します。