Feature Request: Multifile Markdown

[con-f-use]

Including other Markdown files, would be nice. Most other implementations solve this with syntax like {{path/to/file}} or <<[path/to/file]. Here is an example:

# Section 1

{{sections/first.md}}

# Section 2

{{sections/second.md}}

# Section 3

{{sections/third.md}}

Where first.md, second.md and third.md are in a directory called sections relative to the location of above's file and contain markdown and possible file inclusions themselves. It all should be rendered as if the respective content was there instead of the include directive.

[Emanuil Rusev]

Is there a standard that defines this syntax? Thanks.

[con-f-use]

Marked2 does with <<[path/to/file] and they claim the new MultiMarkdown standard uses {{path/to/file}}. Both allow ~/path/to as relative to home and specify the root path as meta data. I also saw a discussion to include it in CommonMark 0.25. Will try to find it.

[Emanuil Rusev]

That's interesting, thanks.

[Harry Dobrev]

For reference, the latest MultiMarkdown project is https://github.com/fletcher/MultiMarkdown-5 and here's the latest relevant spec regarding file transclusion: http://fletcher.github.io/MultiMarkdown-5/transclusion.html

[Taufik Nurrohman]

I would like to have this feature if the syntax is similar to the standard link or image syntax in Markdown, so that we can implement the referenced link style to it. Examples:

+[file not found](path/to/file.txt)

+[file not found](!path/to/file-do-not-parse.txt)

+[file not found][1]

+[file not found][2]

+[1]: path/to/file.txt
+[2]: !path/to/file-do-not-parse.txt

[con-f-use]

Please do not introduce yet another syntax. Stick with the way MultiMarkdown or CommonMark do it.

[Taufik Nurrohman]

Don’t worry I just giving an alternative. It’s up to the community :)

[con-f-use]

I understand, and I find your syntax even better, because its more similar to what Markdown users already know and thus easier to remember and learn. The problem is, it's and inclusion not a link. They are conceptually different thins and should maybe be represented differently (not convinced). But more importantly and the killer argument:

[Harry Dobrev]

Just to say I'm against any change related to multi-file support in Parsedown or Parsedown Extra themselves. I think multifile support and file including should happen externally at one level above the markdown processing. E.g a static-site generator or a file-based CMS could have such a feature and rely on a Markdown parser such as Parsedown just to parse Markdown. Look at Jekyll or a number its competitors/clones where they have separated the site-generator/CMS like features from the parsers and you can switch Markdown parsers easily.

While multi-file support could be very useful (especially for including a file with code inside of a code block) it doesn't require any special support from Markdown perspective to be implemented outside of the parser.

That said a library which uses Parsedown/Parsedown Extra and implements a multi-file feature in a compatible manner with a common standard would be very useful.

Don't forget Parsedown Extra purpose is to conform to the Markdown Extra syntax. Any other syntax support which is completely unsupported in Markdown Extra, would lead to confusion for new users who might think this is from Markdown Extra, but implicitly it would have just created the 15th standard from the cartoon above.

[con-f-use]

Not to mention that some Markdown variants use {{x}} as placeholder for external variables. I.e:

<?php
$x = 'foo';
$parser = new MardownParser();
echo $Extra->text('**{{x}}**'');   // Output: <b>foo</b>
?>

Also handling metadata (#93) on all levels is a bit tricky. Do you do a treewalk to get a metadata tree? Do you just take the top-level metadata? You have convinced me, that it is indeed a bad idea to specify file inclusion as part of the parser.