Запрос на комментарии:Каким должен быть синтаксис для включения фрагментов кода в Markdown?(из внешних файлов)

Question

Я использовал Уценка недавно.

Одна из моих самых больших проблем с Markdown заключается в том, что Markdown не имеет синтаксиса для включения файлов в документ (по сравнению, скажем, с listings упаковка для латекса).

Я хотел бы расширить Markdown для поддержки включения целых и частичных файлов в виде фрагментов кода.Например, это могло бы выглядеть следующим образом:

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

и это поместило бы содержимое bar.rb строки 10-20 в мой документ в качестве code блок.Обоснование заключается в том, что

• документация может обновляться по мере изменения кода.(противкопировать и вставлять, которые всегда устаревают)
• затем вы можете выполнить модульное тестирование точного кода, который есть в документации

Мои вопросы таковы:

1. Каким должен быть синтаксис?
2. Было ли это уже сделано, и я пропускаю это?

Answer 1

Я был бы более склонен придумать общее средство расширения синтаксиса Markdown, а затем использовать его для обеспечения поддержки функции include.Так, например, вы могли бы определить синтаксис следующим образом (на самом деле я не предлагаю этот конкретный синтаксис, просто пример):

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

..где command ссылается на команду, которую анализатор markdown не понимает, но может вызвать что-то другое для ее обработки.Затем вы можете создать функцию включения, которая будет работать с markdown, но на самом деле не будет ее частью.Что - то вроде:

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

О, и если вы сделаете это, я бы, вероятно, не стал предоставлять средства для включения частичного файла, по крайней мере, не используя номера строк - поскольку это означает, что вам придется вернуться назад и отредактировать все вызовы include, если вы измените длину документа, что на самом деле усложняет повторное использование (если бы вы могли придумать способ помечать разделы тегами, это могло бы работать лучше).

Answer 2

В целом я склонен посмотреть, можно ли разумным образом заставить что-то работать с существующим синтаксисом.В настоящее время

    ![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 атрибут для встроенных изображений:Он содержит краткое, понятное человеку описание включаемого файла.

Используя + для меня это интуитивно понятно:Это означает Добавить содержимое этого файла к этому документу приведено здесь.

Answer 3

Я немного опоздал, извините.но reStructuredText уже поддерживает это:http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment