Solicitud de comentarios: ¿Cuál debería ser la sintaxis para incluir fragmentos de código en Markdown? (de archivos externos)

Question

He estado usando Markdown recientemente.

Uno de mis mayores problemas con Markdown es que Markdown no tiene sintaxis para incluir archivos dentro de un documento (vs., digamos, el listados paquete para LaTeX).

Me gustaría extender Markdown para admitir la inclusión de archivos completos y parciales como fragmentos de código. Por ejemplo, podría verse así:

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

y eso pondría el contenido de las líneas bar.rb 10-20 en mi documento como un bloque code . La razón es que

• la documentación se puede actualizar a medida que cambia el código. (frente a copiar y pegar, que siempre queda desactualizado)
• luego puede probar el código exacto que se encuentra en la documentación

Mis preguntas son:

1. ¿Cuál debería ser la sintaxis?
2. ¿Ya se ha hecho esto y me lo estoy perdiendo?

Answer 1

Me inclinaría más por encontrar un medio general para extender la sintaxis de Markdown, y luego usarlo para proporcionar soporte para una función de inclusión. Entonces, por ejemplo, podría definir una sintaxis como (realmente no estoy sugiriendo esta sintaxis en particular, solo un ejemplo):

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

..where command se refiere a un comando que el analizador Markdown no entiende, pero puede llamar a otra cosa para procesarlo. Luego, puede crear una función de inclusión que funcione con Markdown, pero que en realidad no forme parte de ella. Algo así como:

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

Ah, y si haces esto, probablemente no proporcione un medio para incluir un archivo parcial, al menos no utilizando números de línea, ya que significa que tienes que volver y editar todas las llamadas de inclusión si cambias el longitud del documento, lo que en realidad hace que la reutilización sea más difícil (si pudiera encontrar una forma de etiquetar secciones, eso podría funcionar mejor).

Answer 2

Generalmente estoy inclinado a ver si las cosas pueden funcionar con la sintaxis existente de una manera razonable. Actualmente, el

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

La sintaxis

y sus parientes se utilizan para incluir una imagen en el texto. En una vena similar,

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

o

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

se puede usar para incluir texto. En este caso, el texto entre corchetes es como el atributo alt-text para las imágenes en línea: contiene una descripción breve y comprensible del archivo que se incluye.

Usar + es intuitivo para mí: significa agregar el contenido de este archivo a este documento aquí.

Answer 3

Llego un poco tarde, lo siento. pero restructuredText ya es compatible con esto: http: //docutils.sourceforge. net / docs / ref / rst / directives.html # inclusive-an-external-document-fragment