Docs Pipelines のために Ami Pro .SAM を Markdown に変換する

TL;DR

コンテンツがリポジトリ、静的サイトジェネレーター、またはテキストパイプラインに向かう場合は、Markdown を選択してください。Markdown は小さく、差分に優れ、移植可能です：見出し、リスト、表、リンクは保持され、抽出された図はリンクされた画像ファイルになり、方程式は LaTeX を保持できます。Git と組み合わせることで、変換された Ami Pro アーカイブは信頼に頼るのではなく、プルリクエストでレビュー可能になります。変換には Ami Pro Converter を使用してください。

レガシー文書にMarkdownを使用する理由

Docs-as-codeは「ドキュメントを持つ」という意味を変えました。リポジトリ内のコンテンツはバージョン履歴、コードレビュー、自動リンクチェック、ビルドパイプラインを得ます。独自のバイナリ形式のコンテンツはそのどれも得られません — そして.samファイルはさらにそれ以下です、なぜならチェーン内のどのツールもそれを読むことができないからです。

Markdownに変換すると、何十年分の資料を他のすべてと同じワークフローに移動させることができます。1995年のインストール手順は、2002年の改訂版と差分を比較できるファイルになり、プルリクエストで注釈を付け、今四半期のリリースノートと同じ静的サイトジェネレーターを通じて公開することができます。

Markdown は、利用可能な中で最も耐久性のある実用的な選択肢でもあります。これはプレーンテキストで、軽量な規約層が付いています：ソフトウェアなしで読め、数十の実装で解析可能で、必要に応じて HTML、PDF、DOCX またはその他の形式に変換できます。問題全体が、ベンダー形式がそのベンダーよりも長生きしたことから始まったことを考えると、その可搬性こそが重要なポイントです。

何がきれいにマッピングされ、何がそうでないか

Markdown は意図的に最小限であり、それがその強みであり限界でもある。構造はうまく翻訳できるが、提示方法はそうではない。そしてそれは通常問題ない。なぜなら、提示方法は結局置き換えたい層だからである。

見出し — .STY シートの Ami Pro スタイルが Markdown の見出しレベルになり、実際のドキュメント構造を提供します
リスト — 箇条書きリストおよび番号付きリストは、ネストを含む標準のMarkdownリストに変換されます
強調 — 太字と斜体は直接対応します；下線にはMarkdownの対応するものがなく、通常は強調になります
表 — シンプルな表はパイプ表になります。複雑な結合セルのレイアウトは表現できず、HTML フォールバックまたは注記が必要です
画像 — 抽出された WMF/EMF 図はファイルとして書き出され、標準の画像構文で参照されます
方程式 — 数学対応のレンダラーでは LaTeX として利用可能、対応していない場合はリンク付き画像として提供

スタイルシートは見出しを可能にするものです

これは、Markdown変換が役立つか無価値かを決定する詳細です。Markdownには「16ポイント太字ヘルベチカ」の概念はなく、見出しレベルがあります。コンバータがある行が強調された段落ではなくレベル2の見出しであることを知る唯一の方法は、段落スタイルを.STYスタイルシートに対して解決することです。

スタイルシートがある場合、変換された文書は見出しの階層構造を持っており、そこから目次を作成したり、部分ごとに分割したりすることができます。スタイルシートがない場合は、時折太字の行があるものの、単調な段落の連続となり、上記の利点はすべて消えてしまいます。

したがって、ドキュメントパイプライン用にアーカイブを変換する前に、.STYファイルが古いサーバーから正しく移行されたか確認してください。これは1分ほどで済み、プロジェクト全体の結果を決定します。

リポジトリ内の画像の取り扱い

1. 資産の配置先を決定する

ほとんどの静的サイトジェネレーターは、画像を専用のディレクトリに置くか、ページと同じ場所に配置することを想定しています。変換する前にこの規則を選んでおくことで、ファイルを一度だけ移動し、数千のMarkdownファイル全体で参照を名前変更する手間を避けることができます。

2. リポジトリのサイズを確認する

抽出された図は積み重なります。図が含まれる数千の文書は、以前はテキストのみだったリポジトリに数百メガバイトを追加する可能性があります。Git LFS を検討するか、アセットをオブジェクトストレージに保存し、URLで参照してください。

3. ファイル名を正規化する

レガシーアーカイブには、DOS時代の名前、スペース、混在した大文字小文字が多く含まれています。移行中に小文字のハイフン付きの名前に正規化し、公開ページを元の.samファイルにたどれるようにマッピングテーブルを保持してください。

4. 最初に方程式の戦略を選ぶ

あなたのサイトが数学をレンダリングする場合、抽出されたLaTeXを使用して、鮮明で選択可能、検索可能な数式を取得してください。もしレンダリングしない場合は、レンダリングされた画像を使用し、数学が検索できないことを受け入れてください。1つのアーカイブ内で両方を混在させることは避けるべきオプションです。

何千もの変換されたファイルを確認する

誰も三千のMarkdownファイルを読むことはありませんが、GitはDOCXファイルのフォルダではできない方法で選択的なレビューを可能にします。変換結果を1つの大きなコミットとしてブランチに適用し、ファイルごとではなくパターンごとにレビューします。

ここでの主なツールはGrepです。異常に短いファイル、全く見出しのないファイル、未解決の画像参照、解析の欠落を示す孤立した括弧付きマークアップ、エンコーディングの問題を示す置換文字を検索します。それぞれの検索は、数秒である種の失敗を浮き彫りにします。

ついでにパイプラインに自動化を追加しましょう：壊れた内部参照を検出するリンクチェッカー、ジェネレーターが必要とする場合のフロントマター検証、そして画像が欠落しているとビルドが失敗するビルドステップです。それらが通れば、アーカイブは維持されているドキュメントと同じ品質基準にあります。

Markdown が間違った対象である場合

Markdown は意図的に複雑なページレイアウトを表現できず、いくつかの Ami Pro ドキュメントは書かれたというより設計されていたものです — ニュースレター、フォーマットされたフォーム、フレームベースの構成によるレポートカバーなど。これらを Markdown に無理に変換すると、技術的には有効でも実用的には使えないものが生成されます。

同じことは、意味が法的で正確な提示に依存する文書にも当てはまります：履行された契約書、署名済みのフォーム、公式通知などです。それらに関しては、PDF が正確な出力であり、もし Markdown と共に発見可能にしたい場合は、両方に変換し、短い Markdown スタブから PDF へリンクしてください。

選択的であることは妥協ではありません。きれいで構造化されたMarkdownで満たされたドキュメントリポジトリと、固定レイアウトが必要なドキュメント用のリンクされたPDFのセットは、品質の低下した変換が一様に積み重なったものよりも、より良い結果です。

Markdown が古いアーカイブにもたらすもの

これまでなかったバージョン履歴、レビュー、差分比較を文書に
現行ドキュメントと同じ静的サイトジェネレーターで公開可能
どのツールよりも長持ちする、小さく持ち運びやすいプレーンテキストファイル
目次作成や AI 向けチャンク分割に適した見出し構造
画像にならず検索可能なままの LaTeX 数式

古い文書には現代のツールが必要です

リポジトリ内の.samファイルとMarkdownファイルの間のギャップは、単なるフォーマットの変更ではありません。それは、誰も検査できないコンテンツと、チームが書く他のすべてのものと同様にレビュー、検索、そして自動公開に参加できるコンテンツとの違いです。

スタイルシートを確認し、開始前にアセットと方程式の規約を決定し、アーカイブを一度に変換し、読むのではなくgrepで確認してください。その後、他のドキュメントと同じパイプラインに通してください。