コメントのリクエスト:Markdownにコードスニペットを含めるための構文は何ですか? (外部ファイルから)
質問
最近マークダウンを使用しています。
Markdownの最大の問題の1つは、Markdownにドキュメント内にファイルを含めるための構文がないことです(たとえば、 LaTeXの listings
パッケージ。
Markdownを拡張して、コードスニペットとしてファイル全体および部分を含めることをサポートしたいと思います。たとえば、次のようになります。
![:include src/foo/bar.rb](10-20)
そしてそれは bar.rb
行10-20の内容を code
ブロックとしてドキュメントに入れます。その理由は
- ドキュメントは、コードの変更に応じて更新できます。 (対コピーと貼り付けは常に古くなっています)
- その後、ドキュメントにある正確なコードを単体テストできます
私の質問:
- 構文はどうあるべきか
- これはすでに行われているのですか?
解決
Markdown構文を拡張する一般的な手段を考え出し、それを使用してinclude関数のサポートを提供したいと思います。たとえば、次のような構文を定義できます(この特定の構文を実際に提案しているのではなく、単なる例です):
[[command: arg arg arg...]]
.. where command
は、マークダウンパーサーが理解できないコマンドを指しますが、他の何かにコールバックして処理することができます。その後、マークダウンで動作するが実際にはその一部ではないinclude関数を構築できます。次のようなもの:
[[include: src/foo/bar.md]]
ああ、これを行うと、少なくとも行番号を使用しないで、部分的なファイルを含める手段を提供しないでしょう。これは、文書の長さ。実際には再利用が難しくなります(セクションにタグを付ける方法を考え出すことができれば、それがより効果的かもしれません)。
他のヒント
私は一般に、既存の構文を合理的な方法で機能させることができるかどうかを確認したいと思います。現在、
![Example Photo](http://example.com/example.jpg)
構文とその親類は、テキストに画像を含めるために使用されます。同様に、
+[Generic Heading](http://example.com/heading.txt)
または
+[Local Heading](file:///dir/a/b/c/example.txt)
を使用してテキストを含めることができます。この場合、角括弧内のテキストは、インラインイメージの alt-text
属性と同じです。含まれるファイルの人間が理解できる短い説明が含まれています。
+
を使用するのは直感的です。つまり、このファイルの内容をこのドキュメントに追加します。
すみません、すみません。しかし、restructuredTextはすでにこれをサポートしています: http://docutils.sourceforge。 net / docs / ref / rst / directives.html#include-an-external-document-fragment