Request for comments: What should the syntax be to include code snippets in Markdown? (from external files)

Question

I've been using Markdown recently.

One of my biggest problems with Markdown is that Markdown has no syntax for including files within a document (vs., say, the listings package for LaTeX).

I'd like to extend Markdown to support including whole and partial files as code snippets. For instance, it could look like this:

![:include src/foo/bar.rb](10-20)

and that would put the contents of bar.rb lines 10-20 into my document as a code block. The rationale is that

• documentation can be updated as the code changes. (vs. copy and paste which always gets outdated)
• you can then unit test the exact code that is in the documentation

My questions are:

1. What should the syntax be?
2. Has this already been done and I am missing it?

Answer 1

I'd be more inclined to come up with a general means to extend Markdown syntax, and then use that to provide support for an include function. So for example you could define syntax like (I'm not really suggesting this particular syntax, just an example):

[[command: arg arg arg...]]

..where command refers to a command that the markdown parser doesn't understand, but can call back to something else to process it. Then you can build an include function that will work with markdown, but not actually be part of it. Something like:

[[include: src/foo/bar.md]]

Oh and if you do this, I'd probably not provide a means to include a partial file, at least not by using line numbers - as it means you have to go back and edit all the include calls if you change the length of the document, which actually makes reuse harder (if you could come up with a way to tag sections, that might work better).

Answer 2

I am generally inclined to see if things can be made to work withing existing syntax in a reasonable way. Currently, the

    ![Example Photo](http://example.com/example.jpg)

syntax and its relatives are used to include an image in the text. In a similar vein,

    +[Generic Heading](http://example.com/heading.txt)

or

    +[Local Heading](file:///dir/a/b/c/example.txt)

can be used to include text. In this case, the text in the square brackets is just like the alt-text attribute for inline images: It contains a short, human comprehensible description of the file being included.

Using + is intuitive to me: It means add the contents of this file to this document here.

Answer 3

I'm a little late, sorry. but restructuredText already supports this: http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment