PDF の Markdown: リポジトリを持ち歩かずにドキュメントを共有する方法

README、デプロイメント手順、プロジェクトノート: Markdown は記述とバージョンが簡単であるため、多くのドキュメントが Markdown で生まれます。しかし、すべての受信者がコード エディターを開こうとしているわけではありません。 PDF をエクスポートすると、コンテンツがコンバーターが解釈しない機能に依存していない限り、送信が簡単になります。

代表的なスニペットを使用してテストする

50 ページを変換する前に、タイトル、番号付きリスト、コード ブロック、リンクを含むサンプルを選択します。ザPDF のマークダウンは基本的な構造を認識しますが、複雑なテーブル、外部イメージ、コード スニペットのプレゼンテーションは、完全な Markdown レンダラーのプレゼンテーションと必ずしも一致しません。

これは、Markdown にバリエーションがあるために発生します。一部の拡張機能は表、図、脚注を受け入れますが、他の拡張機能はタイトル、リスト、および単純な書式設定のみを解釈します。ファイル.md受信者にすべてのプログラムで同じページが表示されることを保証するものだけではありません。

リポジトリを見られない人のために書く

のような相対リンク../images/flux.pngプロジェクト内では機能しても、プロジェクト外では失われる可能性があります。画像が重要な場合は、説明を含めるか、ローカル ファイルを認識できるエディタを使用して画像をエクスポートします。壊れた URL は役に立たない参照となるため、外部ドキュメントへのリンクも検討する必要があります。

インストール リストには、コマンドが正しい順序で記載されている必要があります。ブロックが明確に区切られていること、およびスラッシュ、ハイフン、引用符などの文字が判読できる状態であることを確認してください。マニュアルでは、コマンドのわずかな違いにより、手順を再現できなくなる可能性があります。

視聴者に合わせてフォーマットを選択する

ドキュメントで共同作業するには、Markdown を主要なソースとして使用してください。朗読版を配布するにはPDFが便利です。検索、アクセス可能なリンク、コピー可能なコードが必要な場合は、適切なエディターで高忠実度のテキスト エクスポートを使用してください。

最後に、生成されたファイルを Markdown プレビューと比較します。プロジェクトを開いたことがない人が PDF の内容だけで手順を理解できるかどうかを考えて読んでください。そうであれば、変換はその役割を果たしたことになります。

ドキュメントはエディターの外でも存続する必要がある

Markdown は、タイトル、リスト、例がプレーン テキストでも表示されるため、ガイドや技術ノートを作成するのに最適です。 PDF でコード、表、または大きな画像のブロックを表現する必要がある場合、問題が発生します。行が長すぎると余白を超えてしまう可能性があり、幅の広い表ではページの向きを変える必要がある場合があります。したがって、マニュアル全体を配布する前に、テスト エクスポートを実行してください。

ローカル ファイルへのリンクがある場合は、受信者がそれらにアクセスできることを確認してください。自分のコンピュータでは機能するパスでも、別のマシンでは何の意味も持たない可能性があります。画像には、単なる「図 1」ではなく、何が表示されているかを説明するキャプションを付けてください。ドキュメントが頻繁に更新される場合は、Markdown ファイルをメイン ソースとして保存し、出版物ごとにバージョン管理された PDF を生成します。