Markdownで技術文書を書いているなら、そのジレンマはご存知でしょう。文書の一部は手書きの文章ですが、目次、コードスニペットの取り込み、レンダリングされた図などは、どこか別の場所から生成されます。その境界線をどのように扱うかは、ワークフローについて多くを物語っています。 ほとんどのドキュメンテーションツールチェーンは、PETやJamalのようなプリプロセッサと同じ方法でそれを解決します。つまり、ソースと出力を分離します。テンプレートファイルを維持し、ビルドステップを実行すると、レンダリングされたドキュメントが結果として得られます。クリーンで予測可能、そして理解しやすいですが、ビルドステップが追加され、出力ファイルは実際に編集したり共有したりするものではありません。