support file transclusion (including contents of a file)

[Timothee Cour]

basically this feature request: github/markup#346

use cases

• including a csv file (rendering it as a table)
• including another markdown (cf rst's include)
• including a LICENSE.txt
• DRY docs: allows including a version number for example
• makes it easier to transform Nim's rst files (which have a few include) to markdown
• embed video

syntax

as proposed here: https://talk.commonmark.org/t/transclusion-or-including-sub-documents-for-reuse/270/3

{{ my_file }} -> include the file and parse it as markdown
{{ my_file[start:end] }} -> include the lines comprised between start and end and parse them as markdown.

there are alternatives that have been proposed in various markdown flavor.

Ideally, it should allow optionally specifying the file type (overriding guessing it from file extension if needed), eg: jpg, csv, md, txt, codebock(?)

caveats

• github doesn't seem to support this feature
  Github doesn't provide this feature even for reStructuredText (rst) which has include directive in the official language spec : github/markup#172

• I'e seen somewhere github doesn't support it because of security concerns, however I'd like to understand more that concern ; it doesn't seem relevant as far as nim-markdown is concerned

• different flavors of markdown use a different syntax for this feature

• other syntax I've seen:

[![Watch the video](https://raw.github.com/GabLeRoux/WebMole/master/ressources/WebMole_Youtube_Video.png)](http://youtu.be/vt5fpE0bzSY)

• other syntax I've seen here https://github.com/sethen/markdown-include

#include "another-markdown-file.md"

links

• https://github.com/iainc/Markdown-Content-Blocks

CSV files are embedded as tables, source code files become code blocks, and embedded text files help writers structure their work:

• Re-use documentation => Modular Markdown for README.md to "include" instead of "link" to another file · Issue #471 · isaacs/github

• https://stackoverflow.com/questions/4279611/how-to-embed-a-video-into-github-readme-md

• README.rst :include: directive doesn't work · Issue #172 · github/markup

• https://pypi.org/project/markdown-include/

• https://github.com/sethen/markdown-include

• idea: include files and long tables · Issue #553 · jgm/pandoc

• Markdown and including multiple files - Stack Overflow

• https://fletcher.github.io/MultiMarkdown-5/transclusion.html

[Ju]

Nice compiled information. Thanks!

I think we can implement it but turn it off by default. Otherwise, it would be conflict to #4.
I'll look into it after fully supporting GFM (v1.0.0).

[Ju]

Close this issue. Nim-markdown is aimed to support commonmark & gfm as of now. File transclusion is not in these specs. It's encouraging to implement it as an extension in library users' projects.

I've added a section to advance usages: Customize Parsing. It provides an example on parsing and rendering for content like #include "filename.md". You can follow the same pattern to support rules such as {{ filename.md }}.