Composing multi-file documents from text sections

michael.raess's Avatar


22 May, 2012 09:11 AM


I would like to suggest an extension of the multi-file functionality:

In addition to linking to entire external files with the <<[path/file] syntax, it would be cool to be able to link to specific sections in a given document using a syntax like <<[path/file#section].

section could be a heading + following paragraphs, or it may be necessary to specify a section with a syntax similar to what is currently used to mark up page breaks.

  1. Support Staff 1 Posted by Brett on 22 May, 2012 11:46 AM

    Brett's Avatar

    How would you foresee using this?

  2. 2 Posted by michael.raess on 22 May, 2012 12:38 PM

    michael.raess's Avatar

    I use a series of documents marked up with MMD, which are bundled together by Marked to provide a project management tool. In this way I use Marked a bit like a Personal Wiki. This has the advantage that I can use txt-files directly, without the detour of html files or another more closed system like TiddlyWiki.

    In my current setup, a project file is a multi-file doc with different sections made up by a series of related files. Each project file contains for instance a 'Next step' section, made up by a separate file and linked to with the <<[path/file] syntax.

    Why separate files? In this way I can create also a 'All Next Steps' file across projects, bundling together all different 'Next step' files.

    With a <<[path/file#section] syntax it would not be necessary to create all these subfiles, since I could create my cross-project files by referring to the respective sections in the project files.

    Was I able to bring my point across?

  3. Support Staff 3 Posted by Brett on 22 May, 2012 01:22 PM

    Brett's Avatar

    Yes, but it's a very narrow use case and there are many variables. For example. what defines a section in a way that would be consistent for everybody's needs? Additional markup syntax isn't ideal, and if the documents are in Markdown at the time of inclusion then we don't have element id's to parse and separate by. Because Marked can handle nested rendering, it gets even more complex because I can't render HTML versions until I have everything concatenated, so doing any XML parsing is not possible at the time of inclusion for individual files.

    I like the idea, but it's not as simple as it sounds. Have any suggestions or thoughts on the above points?

  4. 4 Posted by michael.raess on 22 May, 2012 03:08 PM

    michael.raess's Avatar

    narrow use case:

    I could imagine other uses like a book project or a longer text where parts are drawn from sections of other text files

    how to define a section?

    I would think that headings are natural separators of sections ... the interesting question is at which level?
    The Marked Help tells me that it is possible to force a page break with <!--BREAK-->. Could <!--SECTION--> work in a similar way to signify the division between sections?

  5. Support Staff 5 Posted by Brett on 24 May, 2012 02:01 PM

    Brett's Avatar

    I'll add this to this "to consider" list. No promises, but I understand where you're going with the concept.

Reply to this discussion

Internal reply

Formatting help / Preview (switch to plain text) No formatting (switch to Markdown)

Attaching KB article:


Attached Files

You can attach files up to 10MB

If you don't have an account yet, we need to confirm you're human and not a machine trying to post spam.

Keyboard shortcuts


? Show this help
ESC Blurs the current field

Comment Form

r Focus the comment reply box
^ + ↩ Submit the comment

You can use Command ⌘ instead of Control ^ on Mac